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内 容 提 要 


本 书 共 分 三 部 分 ， 全 面 介绍 如 何 基于 Python 微 框架 Flask 进行 Web 开发 。 第 一 部 分 是 Flask 
简介 ， 介 绍 使 用 Flask 框架 及 扩展 开发 Web 程序 的 必 备 基础 知识 ; 第 二 部 分 则 给 出 一 个 实例 ， 真 
正 带领 大 家 一 步 步 开 发 完整 的 博客 和 社交 应 用 Flasky， 从 而 将 前 述 知识 融会 贯 ， 付 诸 实践 。 第 三 
部 分 介绍 了 发 布 应 用 之 前 必须 考虑 的 事项 ， 如 单元 测试 策略 、 性 能 分 析 技 术 、Flask 程序 的 部 署 方 

本 书 适 合 熟悉 Python 编程 ， 有 意 通过 Flask 全 面 掌控 Web 开发 的 程序 员 学 习 参 考 。 
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和 其 他 框架 相 比 ，Flask 之 所 以 能 脱 阁 而 出 ， 原 因 在 于 它 让 开发 者 做 主 ， 使 其 能 对 程序 具有 
全 面 的 创意 控制 。 或 许 你 曾 听 过 “和 框架 斗争 ”这 一 说 法 。 在 大 多 数 框架 中 ， 当 你 决定 使 用 
的 解决 方案 不 受 框架 官方 支持 时 就 会 发 生 这 种 情况 。 你 可 能 想 使 用 不 同 的 数据 库 引 擎 或 者 不 
同 的 用 户 认证 方法 。 但 是 ， 这 种 偏离 框架 开发 者 设 定 路 线 的 做 法 往往 会 给 你 带 来 很 多 麻烦 。 


Flask 就 不 一 样 了 。 你 喜欢 关系 型 数据 库 ? 很 好 。Flask 支持 所 有 的 关系 型 数据 库 。 或 许 你 
更 喜欢 使 用 NoSQL 数据 库 ? 没 问 题 ，Flash 也 支持 。 想 使 用 自己 开发 的 数据 库 引 擎 ?根本 
用 不 到 数据 库 ? 依 然 没 问题 。 在 Flask 中 ， 你 可 以 自主 选择 程序 的 组 件 ， 如 果 找 不 到 合适 
的 ， 还 可 以 自己 开发 。 就 这 么 简单 。 


























Flask 之 所 以 能 给 用 户 提 供 这 么 大 的 自由 度 ， 关 键 在 于 其 开发 伊始 就 考虑 到 了 扩展 性 。 
Flask 提供 了 一 个 强健 的 核心 ， 其 中 包含 每 个 Web 程序 都 需要 的 基本 功能 ， 而 其 他 功能 则 
交 给 行业 系统 中 的 众多 第 三 方 扩展 ， 当 然 ， 你 也 可 以 自行 开发 。 


在 本 书 中 ， 我 展示 自己 使 用 Flask 开发 Web 程序 的 工作 流程 。 我 不 觉得 这 是 使 用 Flask 开 
发 程序 的 唯一 正确 方式 。 你 应 该 把 我 的 选择 作为 一 种 推荐 方式 ， 而 不 是 真理 。 


大 部 分 软件 开发 类 图 书 都 使 用 短 而 精 的 示例 代码 ， 折 立地 演示 所 介绍 技术 的 功能 ， 让 读者 
自己 去 思考 如 何 使 用 “ 胶 术 ”代码 把 这 些 不 同 的 功能 结合 起 来 ， 从 而 开发 出 完整 可 用 的 程 
序 。 在 本 书 中 ， 我 采用 了 完全 不 同 的 方式 。 我 使 用 的 示例 代码 都 摘自 同一 个 程序 ， 开 始 时 
很 简单 ， 后 续 逐 章 进 行 扩展 。 最 初 这 个 程序 只 有 儿 行 代码 ， 最 后 将 变 成 功能 完善 的 博客 和 
社交 网 络 程序 。 


面向 的 读者 群 


要 想 很 好 地 理解 本 书 内 容 ， 你 需要 具备 一 定 的 Python 编程 经 验 。 阅 读本 书 并 不 要 求 你 了 解 
Flask 的 相关 知识 ， 但 你 最 好 能 理解 Python 中 的 一 些 概念 ， 例 如 包 、 模 块 、 函 数 、 修 饰 器 
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和 面向 对 象 编程 。 熟 悉 异 常 处 理 ， 知 道 如 何 从 栈 跟 踪 中 分 析 问 题 也 对 理解 本 书 有 帮助 。 





学 习 本 书 示例 代码 时 ， 你 大 部 分 时 间 都 要 在 命令 行 中 进行 操作 。 因 此 ， 你 应 该 能 够 熟练 使 
用 自己 操作 系统 中 的 命令 行 。 





现代 Web 程序 都 不 可 避免 地 需要 使 用 HTML、CSS 和 JavaScript。 本 书 开发 的 示例 程序 当 
然 也 用 到 了 这 些 技术 ， 但 本 书 没 有 对 其 进行 详细 介绍 ， 也 没有 说 明 应 该 如 何 使 用 。 因 此 ， 
如 果 你 想 开发 完整 的 程序 ， 且 无 法 向 精通 客户 端 技 术 的 开发 者 寻求 帮助 ， 那 就 需要 对 这 些 
语言 有 一 定 程 度 的 了 解 。 








本 书 附带 的 程序 是 开源 的 ， 我 把 它 上 传 到 了 GitHub。 虽 然 可 以 从 GitHub 上 下 载 ZIP 或 
TAR 格式 的 程序 源码 ， 但 我 还 是 强烈 建议 你 安装 Git 客户 端 ， 以 便 熟 悉 怎 么 使 用 源码 版 本 
控制 系统 ， 至 少 知道 如 何 直 接 从 仓库 中 克隆 源码 以 及 如 何 切 换 到 程序 的 不 同 版 本 。 接 下 来 
的 “如 何 使 用 示例 代码 ”部 分 会 介绍 几 个 你 需要 知道 的 命令 。 你 或 许 希 望 在 自己 的 项 目 中 
使 用 版 本 控制 ， 那 就 把 本 书 作为 学 习 Git 的 一 个 契机 吧 。 











最 后 要 说 明 的 是 ， 本 书 并 不 是 完整 且 详 尽 介绍 Flask 框架 的 手册 。 本 书 介绍 了 Flask 的 大 部 
分 功能 ， 但 你 还 需要 配合 使 用 Flask 官方 文档 (http:/flask.pocoo.org/) 。 


本 书 结构 


本 书 分 为 三 部 分 。 





第 一 部 分 Flask 简介 ”简要 介绍 如 何 使 用 Flask 框架 及 其 一 些 扩 展开 发 Web 程序 。 

















。 第 1 章 ”说明 如 何 安 装 和 设置 Flask 框架 ， 

。 第 2 章 通过 一 个 简单 的 程序 介绍 如 何 使 用 Flask; 

。 第 3 章 介绍 如 何在 Flask 程序 中 使 用 模板 ; 

。 第 4 章 介绍 Web 表单 ， 

。 第 5 章 介绍 数据 库 ; 

。 第 6 章 ”介绍 如 何 实现 电子 邮件 支持 ， 

。 第 7 章 ”提供 一 个 可 供 中 大 型 程序 使 用 的 程序 结构 。 

第 二 部 分 实例 : 社交 博客 程序 ”开发 Flasky， 这 是 我 为 本 书 开发 的 开源 博客 和 社交 网 络 


实 





。 第 8 章 ”实现 用 户 认证 系统 ， 
。 第 9 章 实现 用 户 角色 和 权限 ; 
。 第 10 章 实现 用 户 资 料 页 ; 

。 第 11 章 开发 博客 界面 ; 
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。 第 12 章 实现 关注 功能 
。 第 13 章 ”实现 博客 文章 的 用 户 评论 功能 
”第 14 章 ”实现 应 用 编程 接口 (Application Programming Interface，API)。 


第 三 部 分 成 功 在 望 ” 介 绍 与 开发 程序 没有 直接 关系 ， 但 在 程序 发 布 之 前 要 考虑 的 事项 。 


。 第 15 章 详细 说 明 各 种 单元 测试 策略 ; 

第 16 章 ”简要 介绍 性 能 分 析 技 术 ; 
。 第 17 章 ”说明 Flask 程序 的 部 署 方式 ， 包 含 传统 方式 和 云 方式 ; 
第 18 章 “ 列 出 其 他 资源 。 





如 何 使 用 示例 代码 
本 书 使 用 的 示例 代码 可 在 GitHub 上 获取 ': https://github.com/miguelgrinberg/flasky。 


这 个 仓库 的 提交 历史 被 精心 设置 为 与 本 书 所 介绍 的 功能 顺序 一 致 。 使 用 这 份 代 码 时 ， 我 建 
议 你 从 最 早 的 提交 开始 ， 顺 着 本 书 内 容 的 进度 ， 向 前 推移 查看 提交 列表 。 另 外 ， 你 还 可 以 
从 GitHub 上 下 载 每 次 提交 代码 后 得 到 的 ZIP 或 TAR 文件 。 








如 果 你 决定 使 用 Git 操作 源码 ， 那 么 首先 要 安装 Git 客户 端 (可 以 从 http://git-scm.com/ 下 
载 )。 下 述 命令 就 使 用 Git 下 载 示例 代码 : 


$ git clone https://github.com/miguelgrinberg/flasky.git 


git clone 命令 从 GitHub ee 安装 到 当前 目录 下 的 flasky 文件 夹 中 。 这 个 文件 夹 
中 不 仅 有 源码 ， 还 有 一 个 包含 了 程序 修改 完整 历史 的 Git 仓库 。 


第 1 章 会 要 求 你 签 出 程序 的 初始 发 布 版 本 ， 然 后 在 适当 的 时 候 指 示 你 需要 向 前 推进 查看 提 
交 历 史 。 切 换 提 交 历 史 的 Git 命令 是 git checkout。 下 面 举 个 例子 : 











$ git checkout 1a 


述 命令 中 的 1a 代表 一 个 标签 (tag)， 是 项 目 中 某 次 提交 历史 的 名 字 。 这 个 仓库 的 标签 根 
ee 节 命 名 ， 因 此 本 例 中 的 1a 表示 第 1 章 使 用 程序 的 初始 版 本 。 大 多 数 章 都 不 目 
使 用 一 个 标签 ， 例 如 5a 和 5b 等 分 别 对 应 第 5 章 中 使 用 到 的 不 同 版 本 。 


除了 签 出 程序 源码 的 不 同 版 本 ， 你 可 能 还 需要 进行 一 些 设置 。 例 如 ， 你 有 时 需要 安装 额外 
的 Python 包 ， 或 者 升级 数据 库 。 需 要 执行 这 些 操 作 时 ， 我 会 提醒 级 


一 般 情 况 下 ， 你 无 需 修 改 程序 的 产 文 件 ， 但 如 果 修 改 了 ，Git 会 阻止 你 签 出 其 他 历史 版 本 ， 
因为 这 会 导致 本 地 修改 历史 的 丢失 。 签 出 其 他 历史 版 本 之 前 ， 你 要 把 文件 还 原 到 原始 状 


编 注 1: 也 可 注册 iTuring.cn， 在 本 书页 面 免费 下 载 。 






































态 。 最 简单 的 方法 是 使 用 git reset 命令 : 





$ git reset --hard 
这 个 命令 会 损坏 本 地 修改 ， 所 以 执行 此 命令 前 你 需要 保存 所 有 不 想 丢 失 的 改动 。 


你 可 能 经 常 需要 从 GitHub 上 下 载 修正 和 改进 后 的 源码 用 于 更 新 本 地 仓库 。 完 成 这 个 操作 
的 命令 如 下 所 示 : 








$ git fetch --all 
$ git fetch --tags 
$ git reset --hard origin/master 


git fetch 命令 用 于 利用 GitHub 上 的 远程 仓库 更 新 本 地 仓库 的 提交 历史 和 标签 ， 但 不 会 改 


动 真正 的 源 文件 ， 随 后 执行 的 git reset 命令 才 是 用 于 更 新 文件 的 操作 。 再 次 提醒 ， 执 行 
git reset 命令 后 ， 本 地 修改 会 丢失 。 


另 一 个 有 用 的 操作 是 查看 程序 两 个 版 本 之 间 的 区 别 ， 以 便 了 解 改动 详情 。 在 命令 行 中 ， 你 
可 以 使 用 git diff 命令 进行 查看 。 例 如 ， 执 行 下 述 命令 可 以 查看 2a 和 2b 两 个 修订 版 本 之 
间 的 区 别 : 








$ git diff 2a 2b 


这 个 命令 以 补丁 《patch) 的 形式 显示 区 别 ， 如 果 你 以 前 没有 用 过 补丁 文件 ， 可 能 会 觉得 这 
种 查看 变动 的 方式 不 直观 。 你 可 能 发 现 ，GitHub 网 站 中 显示 的 图 形 化 对 比 更 容易 让 人 理 
解 。 例 如 ， 在 GitHub 中 查看 2a 和 2b 两 个 历史 版 本 的 区 别 ， 可 以 访问 https://github.com/ 
miguelgrinberg/flasky/compare/2a...2b。 


使 用 代码 示例 


本 书 的 目的 是 帮助 你 完成 工作 。 一 般 来 说 ， 你 可 以 在 自己 的 程序 或 者 文档 中 使 用 本 书 附带 
的 示例 代码 。 你 无 需 联系 我 们 获得 使 用 许可 ， 除 非 你 要 复制 大 量 的 代码 。 例 如 ， 使 用 本 书 
中 的 多 个 代码 片段 编写 程序 就 无 需 获 得 许可 。 但 以 CD-ROM 的 形式 销售 或 者 分 发 O'Reilly 
书 中 的 示例 代码 则 需要 获得 许可 。 回 答 问题 时 援引 本 书 内 容 以 及 书 中 示例 代码 ， 无 需 获 得 
许可 。 在 你 自己 的 项 目 文档 中 使 用 本 书 大 量 的 示例 代码 时 ， 则 需要 获得 许可 。 


我 们 不 强制 要 求 署名 ,但 如 果 你 这 么 做 ， 我 们 深 表 感激 。 署 名 一 般 包括 书 名 、 作 者 、 出 
版 社 和 国际 标准 图 书 编号 。 例 如 : Flask Web Development by Miguel Grinberg (O’Reilly). 
Copyright 2014 Miguel Grinberg, 978-1-449-3726-2。 






















































































如 果 你 觉得 自身 情况 不 在 合理 使 用 或 上 述 允 许 的 范围 内 ， 请 通过 邮件 和 我 们 联系 ， 地 址 是 


permissions@oreilly.com 。 




















排版 约定 
本 书 使 用 了 下 述 排版 约定 。 


楷体 
标示 新 术语 。 


等 宽 字 体 (constant width) 


表示 程序 代码 ， 也 表示 正文 中 出 现 的 变量 、 国 数 名 、 数 据 库 、 数 据 类 型 、 环 境 变量 、 


语句 和 关键 字 等 。 


加 粗 等 宽 字 体 (constant width) 
命令 或 是 其 他 应 该 由 用 户 输入 的 内 容 。 





和 斜体 等 宽 字 体 (constant width) 





表示 需要 使 用 用 户 的 输入 值 代替 的 文本 ， 或 者 由 上 下 文 决定 的 值 。 


这 个 图 标 表 示 提 示 或 建议 。 





这 个 图 标 表 示 一 般 性 说 明 。 


Safari®? Books Online 








ee》 Safari Books Online (http:/my.safaribooksonline.comy/?portal=oreilly ) 


Safa 上。 大 应 逢 i 变 的 数字 图 书馆 ， 它 同时 以 





图 书 和 视频 的 形式 出 版 世 


Books Online 界 顶级 技术 和 商务 作家 的 专业 作品 (http://www.safaribooksonline. 


com/content) 。 


Safari Books Online 是 技术 专家 、 软 件 开 发 人 员 、Web 设计 师 、 商 务 人 士 和 创意 人 士 开展 
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调研 、 解 决 问 题 、 学 习 和 认证 培训 的 第 一 手 资料 。 


Safari 在 线 图 书馆 为 组 织 (http:/www.safaribooksonline.com/enterprise)、 政 府 部 门 (http:// 
www.safaribooksonline.com/government) 和 个 人 (http://www.safaribooksonline.com/) 提 
供 了 不 同 的 产品 组 合 和 灵活 的 定价 策略 。 订 阅 者 可 以 在 一 个 开放 搜索 的 全 文 数据 库 中 访 
问 上 千 种 图 书 、 培 训 视 频 和 正式 出 版 之 前 的 书稿 。 这 些 内 容 由 以 下 出 版 社 提 供 : O’Reilly 


Media、 Prentice Hall Professional、 Addison-Wesley Professional、 Microsoft Press、Sams、 












































Que、Peachpit Press、 Focal Press、 Cisco Press、 John Wiley & Sons、 Syngress、 Morgan 
Kaufmann、 IBM Redbooks、 Packt、 Adobe Press、 FT Press、 Apress、 Manning、New 
Riders、McGraw-Hill、Jones && Bartlett 和 Course Technology， 等 等 (http://www.safaribook 
sonline.com/publishers)。 若 想 了 解 关 于 Safari Books Online 的 更 多 信息 ， 请 访问 我 们 的 网 


站 (http://www.safaribooksonline.com ) 。 


联系 我 们 

请 把 对 本 书 的 意见 和 疑问 发 送 给 出 版 社 。 

美国 : 
O’Reilly Media, Inc. 


1005 Gravenstein Highway North 
Sebastopol, CA 95472 








中 国 : 
北京 市 西城 区 西直门 南大 街 2 号 成 铭 大 厦 C 座 807 室 (100035) 
奥 莱 利 技术 咨询 (北京 ) 有限 公司 


O’Reilly 的 每 一 本 书 都 有 专属 网 页 ， 你 可 以 在 那儿 找到 本 书 的 相关 信息 ， 包 括 勘 误 表 、 示 
例 代码 以 及 其 他 信息 。 本 书 的 网 站 地 址 是 : 








http://shop.oreilly.com/product/0636920031116.do。 








如 果 你 对 本 书 有 一 些 建议 或 技术 上 的 疑问 ， 请 发 送 电子 邮件 至 bookquestions@oreilly.com。 








要 了 解 更 多 O’Reilly 图 书 、 培 训 课程 、 会 议和 新 闻 的 信息 ， 请 访问 以 下 网 站 ; 
http:/www.oreilly.com 。 

我 们 在 Facebook 的 地 址 如 下 : http://facebook.com/oreilly 

请 关注 我 们 的 Twitter 动态 : http://twitter.com/oreillymedia 


我 们 的 YouTube 视频 地 址 如 下 : http://www.youtube.com/oreillymedia 
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致谢 

我 一 个 人 是 无 法 完成 这 本 书 的 。 家 人 、 同 事 、 老 友 ， 以 及 写 书 过程 中 认识 的 新 朋友 都 给 了 
我 很 大 的 帮助 。 

我 要 感谢 Brendan Kohler， 他 对 本 书 做 了 详尽 的 技术 审 校 ， 并 为 第 14 章 的 成 型 提供 了 宝贵 
建议 。 我 还 要 感谢 David Baumgold、Todd Brunhoff、Cecil Rock 和 Matthew Hugues， 他 们 
在 本 书 撰写 的 不 同 阶 段 审阅 了 书稿 ， 并 对 涵盖 内 容 和 组 织 方式 给 了 予 了 建设 性 建议 。 


























本 书 示例 代码 的 编写 花费 了 我 的 大 量 精力 。 我 很 感激 Daniel Hofmann 的 帮助 ， 他 对 这 个 
程序 做 了 完整 的 代码 审查 ， 并 指出 了 很 多 可 改进 之 处 。 还 要 感谢 我 十 几 岁 的 儿子 Dylan 
Grinberg， 他 暂时 克服 了 Minecraft 这 款 游 戏 的 强大 吸引 力 ， 用 几 周 时 间 帮 助 我 在 不 同 平台 
上 测试 这 些 代码 。 








O’Reilly 有 个 极 好 的 项 目 名 为 Early Release (提早 发 布 )， 可 以 让 迫不及待 的 读者 在 图 书 所 
写 过 程 中 就 进行 阅读 。 很 多 抢先 阅读 的 读者 并 不 局 限于 阅读 本 书 ， 还 加 入 了 讨论 行列 ， 讨 
论 他 们 使 用 本 书 的 体验 ， 这 为 本 书 的 改进 做 出 了 极 大 贡献 。 在 这 些 读者 中 ， 我 要 特别 感谢 
Sundeep Gupta、Dan Caron、Brian Wisti 和 Cody Scott 对 本 书 所 做 的 贡献 。 











O’Reilly Media 的 工作 人 员 始 终 陪 伴 着 我 。 首 先 我 要 特别 感谢 本 书 的 编辑 Meghan 
Blanchette， 她 从 我 们 见面 的 第 一 天 起 ， 就 给 予 我 无 尽 的 支持 、 建 议和 协助 。 她 把 我 写作 第 
一 本 书 的 过 程 变 成 了 美好 的 回忆 。 


最 后 ， 请 让 我 对 Flask 社区 表示 由 囊 的 感谢 。 














第 一 部 分 





Flask 简 介 


第 1 
安 





沫 攻 


在 大 多 数 标准 中 ，Flask (http://flask.pocoo.org/) 都 算是 小 型 框架 ， 小 到 可 以 称 为 “ 微 杠 
架 ”。Flask 非常 小 ， 因 此 你 一 旦 能 够 熟练 使 用 它 ， 很 可 能 就 能 读 懂 它 所 有 的 源码 。 


出 








但 是 ， 小 并 不 意味 着 它 比 其 他 框架 的 功能 少 。Flask 自 开 发 伊始 就 被 设计 为 可 扩展 的 框架 ， 
它 具 有 一 个 包含 基本 服务 的 强健 核心 ， 其 他 功能 则 可 通过 扩展 实现 。 你 可 以 自己 挑选 所 需 
的 扩展 包 ， 组 成 一 个 没有 附加 功能 的 精益 组 合 ， 从 而 完全 精确 满足 自身 需求 。 








Flask 有 两 个 主要 依赖 : 路由、 调试 和 Web 服务 器 网 关 接口 (Web Server Gateway Interface， 
WSGI) 子 系统 由 Werkzeug (http://werkzeug.pocoo.org/) 提供 ， 模板 系统 由 Jinja2 (http:// 
jinja.pocoo.org/) 提供 。Werkzeug 和 Jinjia2 都 是 由 Flask 的 核心 开发 者 开发 而 成 。 











Flask 并 不 原生 支持 数据 库 访 问 、Web 表单 验证 和 用 户 认证 等 高 级 功能 。 这 些 功能 以 及 其 
他 大 多 数 Web 程序 中 需要 的 核心 服务 都 以 扩展 的 形式 实现 ， 然 后 再 与 核心 包 集成 。 开 发 者 
可 以 任意 挑选 符合 项 目 需求 的 扩展 ， 甚 至 可 以 自行 开发 。 这 和 大 型 框架 的 做 法 相反 ， 大 型 
框架 往往 已 经 替 你 做 出 了 大 多 数 决定 ， 难 以 《有 时 甚至 不 允许 ) 使 用 替代 方案 。 


本 章 介绍 如 何 安装 Flask。 在 这 一 学 习 过 程 中 ， 你 只 需要 一 台 安 装 了 Python 的 电脑 。 












































本 书 中 的 代码 示例 已 经 通过 Python 2.7 和 Python 3.3 的 测试 ， 所 以 我 们 强 列 
建议 大 家 选用 这 两 个 版 本 。 





1.1 使 用 虚拟 环境 


安装 Flask 最 便捷 的 方式 是 使 用 虚拟 环境 。 虚 拟 环境 是 Python 解释 器 的 一 个 私有 副本 ， 在 
这 个 环境 中 你 可 以 安装 私有 包 ， 而 且 不 会 影响 系统 中 安装 的 全 局 Python 解释 器 。 


虚拟 环境 非常 有 用 ， 可 以 在 系统 的 Python 解释 器 中 避免 包 的 混乱 和 版 本 的 冲突 。 为 每 个 程 
序 单独 创建 虚拟 环境 可 以 保证 程序 只 能 访问 虚拟 环境 中 的 包 ， 从 而 保持 全 局 解释 器 的 干净 
整洁 ， 使 其 只 作为 创建 (更 多 ) 虚拟 环境 的 源 。 使 用 虚拟 环境 还 有 个 好 处 ， 那 就 是 不 需要 
管理 员 权限 。 








虚拟 环境 使 用 第 三 方 实用 工具 virtualenv 创建 。 输 入 以 下 命令 可 以 检查 系统 是 否 安装 了 


VirtuaLenv ， 


$ virtualenv --version 

















如 果 结 果 显 示 错 误 ， 你 就 需要 安装 这 个 工具 。 


Python 3.3 通过 venv 模块 原生 支持 虚拟 环境 ， 命 令 为 pyvenv。pyvenv 可 以 禁 
代 virtualenv。 不 过 要 注意 ， 在 Python 3.3 中 使 用 pyvenv 命令 创建 的 虚拟 环 
境 不 包含 pip， 你 需要 进行 手动 安装 。Python 3.4 改进 了 这 一 缺陷 ，pyvenv 完 
全 可 以 代替 virtualenv。 


























大 多 数 Linux 发 行 版 都 提供 了 virtualenv 包 。 例 如 ，Ubuntu 用 户 可 以 使 用 下 述 命令 安 
装 它 : 


$ sudo apt-get install python-virtualenv 
如 果 你 的 电脑 是 Mac OS X 系统 ， 就 可 以 使 用 easy_install 安装 virtualenv: 


$ sudo easy_install virtualenv 

















如 果 你 使 用 微软 的 Windows 系统 或 其 他 没有 官方 virtualenv 包 的 操作 系统 ， 那 么 安装 过 
程 要 稍微 复杂 一 点 。 




















在 浏览 器 中 输入 网 址 https://bitbucket.org/pypa/setuptools， 回 车 后 会 进入 setuptools 安装 程 
序 的 主页 。 在 这 个 页 面 中 找到 下 载 安 装 脚本 的 链接 ， 脚 本 名 为 ez_setup.py。 把 这 个 文件 保 
存 到 电脑 的 一 个 临时 文件 夹 中 ， 然 后 在 这 个 文件 夹 中 执行 以 下 命令 : 





$ python ez_setup.py 
$ easy_install virtuaLenv 








上 述 命令 必须 以 具有 管理 员 权限 的 用 户 身份 执行 。 在 微软 Windows 系统 中 ， 
请 使 用 “以 管理 员 身 份 运行 ”选项 打开 命令 行 窗口 ， 在 基于 Unix 的 系统 中 ， 
要 在 上 面 两 个 命令 前 加 上 sudo， 或 者 以 根 用 户 身份 执行 。 一 旦 安装 完毕 ， 
virtualenv 实用 工具 就 可 以 从 常规 账户 中 调用 。 




















现在 你 要 新 建 一 个 文件 夹 ， 用 来 保存 示例 代码 (示例 代码 可 从 GitHub 库 中 获取 )。 我 们 在 
前 言 的 “如 何 使 用 示例 代码 ”一 节 中 说 过 ， 获 取 示 例 代码 最 简便 的 方式 是 使 用 Git 客户 端 
直接 从 GitHub 下 载 。 下 述 命令 从 GitHub 下 载 示 例 代码 ， 并 把 程序 文件 夹 切换 到 “1a” 版 
本 ， 即 程序 的 初始 版 本 : 











$ git clone https://github.com/miguelgrinberg/flasky.git 
$ cd flasky 
$ git checkout 1a 





下 一 步 是 使 用 virtualenv 命令 在 flasky 文件 夹 中 创建 Python 虚拟 环境 。 这 个 命令 只 有 一 
个 必需 的 参数 ， 即 虚拟 环境 的 名 字 。 创 建 虚拟 环境 后 ， 当 前 文件 夹 中 会 出 现 一 个 子 文件 
夹 ， 名 字 就 是 上 述 命令 中 指定 的 参数 ， 与 虚拟 环境 相关 的 文件 都 保存 在 这 个 子 文件 夹 中 。 
按照 惯例 ， 一 般 虚 拟 环境 会 被 命名 为 venv: 








$ virtualenv venv 

New python executable in venv/bin/python2.7 
Also creating executable in venv/bin/python 
Installing setuptools............ done. 
Installing pips sere oes done. 


现在 ，flasky 文件 夹 中 就 有 了 一 个 名 为 venv 的 子 文件 夹 ， 它 保存 一 个 全 新 的 虚拟 环境 ， 其 
中 有 一 个 私有 的 Python 解释 器 。 在 使 用 这 个 虚拟 环境 之 前 ， 你 需要 先 将 其 “激活 ”。 如 果 
你 使 用 bash 命令 行 (Linux 和 Mac OS X 用 户 )， 可 以 通过 下 面 的 命令 激活 这 个 虚拟 环境 : 





$ source venv/bin/activate 

















如 果 使 用 微软 Windows 系统 ， 激 活命 令 是 : 
$ venv\Scripts\activate 
虚拟 环境 被 激活 后 ， 其 中 Python 解释 器 的 路 径 就 被 添加 进 PATH 中 ， 但 这 种 改变 不 是 永久 


性 的 ， 它 只 会 影响 当前 的 命令 行 会 话 。 为 了 提醒 你 已 经 激活 了 虚拟 环境 ， 激 活 虚 拟 环境 的 
命令 会 修改 命令 行 提 示 符 ， 加 入 环境 名 : 





(venv) $ 


当 虚 拟 环境 中 的 工作 完成 后 ， 如 果 你 想 回 到 全 局 Python 解释 器 中 ， 可 以 在 命令 行 提示 符 下 
输入 deactivate。 








1.2 ”使 用 pip 安 装 Python 包 


大 多 数 Python 包 都 使 用 pip 实用 工具 安装 ， 使 用 virtualenv 创建 虚拟 环境 时 会 自动 安装 
pitp。 激 活 虚 拟 环境 后 ，pip 所 在 的 路 径 会 被 添加 进 PATH。 


如 果 你 在 Python 3.3 中 使 用 pyvenv 创建 虚拟 环境 ， 那 就 需要 手动 安装 pip。 
安装 方法 参见 pip 的 网 站 (https://pip.pypa.io/en/latest/installing.html)。 在 
Python 3.4 中 ，pyvenv 会 自动 安装 pip。 











执行 下 述 命 令 可 在 虚拟 环境 中 安装 Flask: 
(venv) $ pip install flask 


执行 上 述 命令 ， 你 就 在 虚拟 环境 中 安装 Flask 及 其 依赖 了 。 要 想 验 证 Flask 是 否 正确 安装 ， 
你 可 以 启动 Python 解释 器 ， 党 试 导 入 Flask: 
(venv) $ python 


>>> import flask 
>>> 





如 果 没 有 看 到 错误 提醒 ， 那 茶 喜 你 
第 一 个 Web 程序 了 。 


你 已 经 可 以 开始 学 习 第 2 章 的 内 容 ， 了 解 如 何 开发 





第 2 章 


程序 的 基本 结构 





本 章 将 带 你 了 解 Flask 程序 各 部 分 的 作用 ， 编 写 并 运行 第 一 个 Flask Web 程序 。 


2.1 初始 化 


所 有 Flask 程序 都 必须 创建 一 个 程序 实例 。Web 服务 器 使 用 一 种 名 为 Web 服务 ws 口 
(Web Server Gateway Interface，WSGI) 的 协议 ， 把 接收 自 客户 端的 所 有 请 求 都 转交 给 
个 对 象 处 理 。 程 序 实例 是 Flask 类 的 对 象 ， 经 常 使 用 下 述 代码 创建 : 








from flask import Flask 
app = Flask(__name_) 





Flask 类 的 构造 函数 只 有 一 个 必须 指定 的 参数 ， 即 程序 主 模块 或 包 的 名 字 。 在 大 多 数 程序 
中 ，Python 的 __name__ 变量 就 是 所 需 的 值 。 





将 构造 国 数 的 name 参数 传 给 Flask 程序 ， 这 一 点 可 能 会 让 Flask 开发 新 手心 
生 迷 惑 。Flask 用 这 个 参数 决定 程序 的 根 上 目录， 以 便 稍 后 能 够 找到 相对 于 程 
序 根 目 录 的 资源 文件 位 置 。 








后 文 会 介绍 更 复杂 的 程序 初始 化 方式 ， 对 于 简单 的 程序 来 说 ， 上 面 的 代码 足够 了 。 


2.2 ”路 由 和 视图 函数 


客户 端 (例如 Web 浏览 器 ) 把 请 求 发 送 给 Web 服务 器 ，Web 服务 器 再 把 请 求 发 送 给 Flask 

















程序 实例 。 程 序 实 例 需 要 知道 对 每 个 URL 请 求 运行 哪些 代码 ， 所 以 保存 了 一 个 URL 到 
Python 函数 的 映射 关系 。 处 理 URL 和 函数 之 间 关 系 的 程序 称 为 路 由 。 





























在 Flask 程序 中 定义 路 由 的 最 简便 方式 ， 是 使 用 程序 实例 提供 的 app.route 修饰 器 ， 把 修 
饰 的 函数 注册 为 路 由 。 下 面 的 例子 说 明了 如 何 使 用 这 个 修饰 右 声 明 路 由 ， 








@app.route('/') 
def index(): 
return '<h1i>Hello World!</h1>" 


修饰 器 是 Python 语言 的 标准 特性 ， 可 以 使 用 不 同 的 方式 修改 函数 的 行为 。 惯 
常用 法 是 使 用 修饰 器 把 函数 注册 为 事件 的 处 理 程序 。 


前 例 把 index() 函数 注册 为 程序 根 地 址 的 处 理 程序 。 如 果 部 署 程序 的 服务 器 域名 为 www. 
example.com， 在 浏 览 器 中 访问 http://www.example.com 后 ， 会 触发 服务 器 执行 tndex() 函 
数 。 这 个 国 数 的 返回 值 称 为 响应 ， 是 客户 端 接 收 到 的 内 容 。 如 果 客 户 端 是 Web 浏览 器 ， 响 
应 就 是 显示 给 用 户 查 看 的 文档 。 











像 index() 这 样 的 函数 称 为 视图 函数 (view function)。 视 图 函数 返回 的 响应 可 以 是 包含 
HTML 的 简单 字符 串 ， 也 可 以 是 复杂 的 表单 ， 后 文 会 介绍 。 


在 Python 代码 中 嵌入 响应 字符 串 会 导致 代码 难以 维护 ， 此 处 这 么 做 只 是 为 了 
介绍 响应 的 概念 。 你 将 在 第 3 章 了 解 生成 响应 的 正确 方法 。 








如 果 你 仔细 观察 日 常 所 用 服务 的 某 些 URL 格式 ， 会 发 现 很 多 地 址 中 都 包含 可 变 部 分 。 例 
如 ， 你 的 Facebook 资料 页 面 的 地 址 是 http://www.facebook.com/<your-name>， 用 户 名 
(your-name) 是 地 址 的 一 部 分 。Flask 支持 这 种 形式 的 URL， 只 需 在 route 修饰 器 中 使 用 特 
殊 的 句法 即 可 。 下 例 定 义 的 路 由 中 就 有 一 部 分 是 动态 名 字 : 





Qapp.route(' /user/<name> ') 
def user(name): 
return '<h1>HeLLo，%s!</h1>' % name 


尖 括 号 中 的 内 容 就 是 动态 部 分 ， 任 何 能 匹配 静态 部 分 的 URL 都 会 映射 到 这 个 路 由 上 。 调 


用 视图 函数 时 ，Flask 会 将 动态 部 分 作为 参数 传 入 函数 。 在 这 个 视图 函数 中 ， 参 数 用 于 生 
成 针对 个 人 的 欢迎 消息 。 








路 由 中 的 动态 部 分 默认 使 用 字符 串 ， 不 过 也 可 使 用 类 型 定义 。 例 如 ， 路 由 /user/<int:id> 
只 会 匹配 动态 片段 id 为 整数 的 URL。Flask 支持 在 路 由 中 使 用 int、float 和 path 类 型 。 
path 类 型 也 是 字符 串 ， 但 不 把 斜 线 视 作 分 隔 符 ， 而 将 其 当 作 动 态 片段 的 一 部 分 。 


2.3 ”启动 服务 器 


程序 实例 用 run 方法 启动 Flask 集成 的 开发 Web 服务 器 : 

















if _ name _ == '_ main _': 
app.run(debug=True) 

__name_ =='_main__' 是 Python 的 惯常 用 法 ， 在 这 里 确保 直接 执行 这 个 脚本 时 才 启 动 开 发 

Web 服务 器 。 如 果 这 个 脚本 由 其 他 脚本 引入 ,程序 假定 父 级 脚本 会 启动 不 同 的 服务 器 ， 因 

此 不 会 执行 app. run()。 


服务 器 局 动 后 ， 会 进入 轮 询 ， 等 待 并 处 理 请 求 。 轮 询 会 一 直 运 行 ， 直 到 程序 停止 ， 比 如 按 
Ctrl-C 键 。 











有 一 些 选 项 参数 可 被 app.run() 国 数 接受 用 于 设置 Web 服务 器 的 操作 模式 。 在 开发 过 程 中 
启用 调试 模式 会 带 来 一 些 便利 ， 比 如 说 激活 调试 器 和 重 载 程序 。 要 想 启 用 调试 模式 ， 我 们 
可 以 把 debug 参数 设 为 True。 


Flask 提供 的 Web 服务 器 不 适合 在 生产 环境 中 使 用 。 第 17 章 会 介绍 生产 环 
这 Web 服务 器 。 





2.4 一 个 完整 的 程序 


前 儿 市 介绍 了 Flask Web 程序 的 不 同 组 成 部 分 ， 现 在 是 时 候 开 发 一 个 程序 了 。 整 个 hello.py 
程序 脚本 就 是 把 前 面 介 绍 的 三 部 分 合并 到 一 个 文件 中 。 程 序 代 码 如 示例 2-1 所 示 。 








示例 2-1 hello.py: 一 个 完整 的 Flask 程序 


from fLask import FLask 
app = Flask(__name_ ) 


@app.route('/') 
def index(): 
return '<hi>Hello NorLd!</h1>' 


if _ name _ == '__main 


app.run(debug=True) 
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如 果 你 已 经 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库， 那么 可 以 执行 git 
checkout 2a 签 出 程序 的 这 个 版 本 。 








要 想 运 行 这 个 程序 ， 请 确保 激活 了 你 之 前 创建 的 虚拟 环境 ， 并 在 其 中 安装 了 Flask。 现 在 
打开 Web 浏览 器 ， 在 地 址 栏 中 输入 http://127.0.0.1:5000/。 图 2-1 是 浏览 器 连接 到 程序 后 的 





eee localhost:5000 we 
| @ localhost:5000 © LReades]y 


es 一- 


Hello World! 






































2-1 hello.py Flask 程序 
后 使 用 下 述 命令 启动 程序 : 
(venv) $ python hello.py 


* Running on http://127.0.0.1:5000/ 
* Restarting with reloader 


如 果 你 输入 其 他 地 址 ， 程 序 将 不 知道 如 何 处 理 ， 因 此 会 向 浏览 器 返回 错误 代码 404。 访 问 
不 存在 的 网 页 时 ， 你 也 会 经 常 看 到 这 个 熟悉 的 错误 。 


示例 2-2 是 这 个 程序 的 增强 版 ， 添 加 了 一 个 动态 路 由 。 访 问 这 个 地 址 时 ， 你 会 看 到 一 则 针 
对 个 人 的 欢迎 消息 。 


示例 2-2 hello.py: 包含 动态 路 由 的 Flask 程序 
from fLask import FLask 
app = FLask(_name__) 


@app.route('/') 
def index(): 
return '<hi>Hello World!</h1>" 


@app.route('/user/<name>') 





def user(name): 
return '<hi>Hello, %s!</h1i>' % name 


if _ name__ == '__main__ 


app.run(debug=True) 


如 果 你 已 经 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库， 那么 可 以 执行 git 
checkout 2b 签 出 程序 的 这 个 版 本 。 








测试 动态 路 由 前 ， 你 要 确保 服务 器 正在 运行 中 ， 然 后 访问 http://localhost:5000/user/Dave。 
程序 会 显示 一 个 使 用 name 动态 参数 生成 的 欢迎 消息 。 请 尝试 使 用 不 同 的 名 字 ， 可 以 看 到 视 
图 函数 总 是 使 用 指定 的 名 字 生 成 响应 。 图 2-2 展示 了 一 个 示例 。 











e@ee localhost:5000/user/Dave/ wo 
Le localhost 5000/， 








Hello, Davel 

















2-2 ”动态 路 由 


2.5 ” 请求- 响应 循环 


现在 你 已 经 开发 了 一 个 简单 的 Flask 程序 ， 或 许 希 望 进 一 步 了 解 Flask 的 工作 方式 。 下 面 儿 
节 将 介绍 这 个 框架 的 一 些 设 计 理 念 。 


2.5.1 程序 和 请 求 上 下 文 
Flask 从 客户 端 收 到 请 求 时 ， 要 让 视图 函数 能 访问 一 些 对 象 ， 这 样 才 能 处 理 请 求 。 请 求 对 
象 就 是 一 个 很 好 的 例子 ， 它 封装 了 客户 端 发 送 的 HTTP 请 求 。 


要 想 让 视图 函数 能 够 访问 请 求 对 象 ， 一 个 显而易见 的 方式 是 将 其 作为 参数 传 入 视图 函数 ， 
不 过 这 会 导致 程序 中 的 每 个 视图 函数 都 增加 一 个 参数 。 除 了 访问 请 求 对 象 ， 如 果 视 图 函数 
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在 处 理 请 求 时 还 要 访问 其 他 对 象 ， 情 况 会 变 得 更 糟 。 








为 了 避免 大 量 可 有 可 无 的 参数 把 视图 函数 弄 得 一 团 糟 ，Flask 使 用 上 下 文 临 时 把 某 些 对 象 
变 为 全 局 可 访问 。 有 了 上 下 文 ， 就 可 以 写 出 下 面 的 视图 函数 : 











from flask import request 


@app.route('/') 

def index(): 
User_agent = request.headers.get('User-Agent') 
return '<p>Your browser is %s</p>' % user_agent 


注意 在 这 个 视图 函数 中 我 们 如 何 把 request 当 作 全 局 变量 使 用 。 事 实 上 ，request 不 可 能 是 
全 局 变量 。 试 想 ， 在 多 线程 服务 器 中 ， 多 个 线程 同时 处 理 不 同 客 户 端 发 送 的 不 同 请 求 时 ， 
每 个 线程 看 到 的 request 对 象 必然 不 同 。Falsk 使 用 上 下 文 让 特定 的 变量 在 一 个 线程 中 全 局 
可 访问 ， 与 此 同时 却 不 会 干扰 其 他 线程 。 
































线程 是 可 单独 管理 的 最 小 指令 集 。 进 程 经 常 使 用 多 个 活动 线程 ， 有 时 还 会 共 
享 内 存 或 文件 句柄 等 资源 。 多 线程 Web 服务 器 会 创建 一 个 线程 池 ， 再 从 线 
程 池 中 选择 一 个 线程 用 于 处 理 接收 到 的 请 求 。 


























在 Flask 中 有 两 种 上 下 文 : 程序 上 下 文 和 请 求 上 下 文 。 表 2-1 列 出 了 这 两 种 上 下 文 提供 的 


二 
变量 。 


表 2-1 Flask 上 下 文 全 局 变量 























变量 名 J Re 说 ” 明 

current_app 程序 上 下 文 当前 激活 程序 的 程序 实例 

g 程序 上 下 文 处 理 请 求 时 用 作 临 时 存储 的 对 象 。 每 次 请 求 都 会 重 设 这 个 变量 
request 请 求 上 下 文 请 求 对 象 ， 封 装 了 客户 端 发 出 的 HTTP 请 求 中 的 内 容 

session 请 求 上 下 文 用 户 会 话 ， 用 于 存储 请 求 之 间 需 要 “ 记 住 ”的 值 的 词典 
































Flask 在 分 发 请 求 之 前 激活 (或 推送 ) 程序 和 请 求 上 下 文 ， 请 求 处 理 完成 后 再 将 其 删除 。 程 
序 上 下 文 被 推送 后 ， 就 可 以 在 线程 中 使 用 current_app 和 9 变量 。 类 似 地 ， 请 求 上 下 文 被 
推送 后 ， 就 可 以 使 用 request 和 session 变量 。 如 果 使 用 这 些 变量 时 我 们 没有 油 活 程序 上 
下 文 或 请 求 上 下 文 ， 就 会 导致 错误 。 如 果 你 不 知道 为 什么 这 4 个 上 下 文 变量 如 此 有 用 ， 先 
别 担心 ， 后 面 的 章节 会 详细 说 明 。 











下 面 这 个 Python shell 会 话 演 示 了 程序 上 下 文 的 使 用 方法 : 


>>> from hello import app 
>>> from flask import current_app 
>>> current_app.name 
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Traceback (most recent call last): 


RuntimeError: working outside of application context 
>>> app_ctx = app.app_context() 

>>> app_ctx.push() 

>>> current_app.name 

'hello' 

>>> app_ctx.pop() 


在 这 个 例子 中 ， 疫 激活 程序 上 下 文 之 前 就 调用 current_app.name 会 导致 错误 ， 但 推送 完 上 


下 文 之 后 就 可 以 调用 了 。 注 意 ， 在 程序 实例 上 调用 app.app_context() 可 获得 一 个 程序 上 
下 文 ， 


2.5.2 ”请 求 调度 

程序 收 到 客户 端 发 来 的 请 求 时 ， 要 找到 处 理 该 请 求 的 视图 函数 。 为 了 完成 这 个 任务 ，Flask 
会 在 程序 的 URL 映射 中 查找 请 求 的 URL。URL 映射 是 URL 和 视图 函数 之 间 的 对 应 关系 。 
Flask 使 用 app. route 修饰 器 或 者 非 修 饰 器 形式 的 app.add_url_rule() 生成 映射 。 


























要 想 查 看 Flask 程序 中 的 URL 映射 是 什么 样子 ， 我 们 可 以 在 Python shell 中 检查 为 hello.py 
生成 的 映射 。 测 试 之 前 ， 请 确保 你 激活 了 虚拟 环境 : 








(venv) $ python 

>>> from hello import app 

>>> app.UrL_map 

Map([<Rule '/' (HEAD, OPTIONS, GET) -> index>, 

<Rule '/static/<filename>' (HEAD, OPTIONS, GET) -> static>, 
<Rule '/user/<name>' (HEAD, OPTIONS, GET) -> user>]) 


/ 和 /user/<name> 路 由 在 程序 中 使 用 app.route 修饰 器 定义 。/static/<filename> 路 由 是 
Flask 添加 的 特殊 路 由 ， 用 于 访问 静态 文件 。 第 3 章 会 详细 介绍 静态 文件 。 

















URL 映射 中 的 HEAD、O0ptions、GET 是 请 求 方法 ， 由 路 由 进行 处 理 。Flask 为 每 个 路 由 都 指 
定 了 请 求 方法 ， 这 样 不 同 的 请 求 方法 发 送 到 相同 的 URL 上 时 ,会 使 用 不 同 的 视图 函数 进 
行 处 理 。HEAD 和 0PTIONS 方法 由 Flask 自动 处 理 ， 因 此 可 以 这 么 说 ， 在 这 个 程序 中 ，URL 
映射 中 的 3 个 路 由 都 使 用 GET 方法 。 第 4 章 会 介绍 如 何 为 路 由 指定 不 同 的 请 求 方法 。 




















2.5.3 ”请 求 钧 子 

有 时 在 处 理 请 求 之 前 或 之 后 执行 代码 会 很 有 用 。 例 如 ， 在 请 求 开始 时 ， 我 们 可 能 需要 创 
建 数 据 库 连 接 或 者 认证 发 起 请 求 的 用 户 。 为 了 避免 在 每 个 视图 函数 中 都 使 用 重复 的 代码 ， 
Flask 提供 了 注册 通用 函数 的 功能 ， 注 册 的 函数 可 在 请 求 被 分 发 到 视图 函数 之 前 或 之 后 
调用 。 

















请 求 钓 子 使 用 修饰 器 实现 。Flask 支持 以 下 4 种 钩子 。 
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。 before_first_request: 注册 一 个 函数 ， 在 处 理 第 一 个 请 求 之 前 运行 。 

。 before_request: 注册 一 个 函数 ， 在 每 次 请 求 之 前 运行 。 

。 after_request: 注册 一 个 函数 ， 如 果 没 有 未 处 理 的 异常 抛 出 ， 在 每 次 请 求 之 后 运行 。 

。 teardown_request: 注册 一 个 函数 ， 即 使 有 未 处 理 的 异常 抛 出 ， 也 在 每 次 请 求 之 后 运行 。 


在 请 求 钧 子 函 数 和 视图 函数 之 间 共 享 数 据 一 般 使 用 上 下 文 全 局 变量 g。 例 如 ，before_ 
request 处 理 程序 可 以 从 数据 库 中 加 载 已 登录 用 户 ， 并 将 其 保存 到 g.user 中 。 随 后 调用 视 
图 函数 时 ， 视 图 函数 再 使 用 g.user 获取 用 户 。 















































请 求 钧 子 的 用 法 会 在 后 续 章 中 介 如 果 你 现在 不 太 理 解 ， 也 不 用 担心 。 
2.5.4 响应 


Flask 调用 视图 函数 后 ， 会 将 其 返回 值 作为 响应 的 内 容 。 大 多 数 情况 下 ， 响 应 就 是 一 个 简 
单 的 字符 串 ， 作 为 HTML 页 面 回 送 客户 端 。 














但 HITP 协议 需要 的 不 仅 是 作为 请 求 响应 的 字符 串 。HTTP 响应 中 一 个 很 重要 的 部 分 是 状 
态 码 ，Flask 默认 设 为 200， 这 个 代码 表明 请 求 已 经 被 成 功 处 理 。 


如 果 视 图 函数 返回 的 响应 需要 使 用 不 同 的 状态 码 ， 那 么 可 以 把 数字 代码 作为 第 二 个 返 
值 ， 添 加 到 响应 文本 之 后 。 例 如 ， 下 述 视图 E a 











@app.route('/') 
def index(): 
return '<h1>Bad Request</h1i>', 400 





视图 函数 返回 的 响应 还 可 接受 第 三 个 参数 ， 这 是 一 个 由 首部 (header) 组 成 的 字典 ， 可 以 
添加 到 HTTP 响应 中 。 一 般 情况 下 并 不 需要 这 么 做 ， 不 过 你 会 在 第 14 章 看 到 一 个 例子 。 

















如 果 不 想 返回 由 1 个 、2 个 或 3 个 值 组 成 的 元 组 ，Flask 视图 函数 还 可 以 返回 Response 对 
象 。make_response() 函数 可 接受 1 个、 2 个 或 3 个 参数 (和 视图 函数 的 返回 值 一 样 )， 并 
返回 一 个 ee 对 象 。 有 时 我 们 需要 在 视图 国 数 中 进行 这 种 转换 ， 然 后 在 响应 对 象 上 调 
用 各 各 方法， 进一步 设置 响应 。 下 例 创建 了 一 个 响应 对 象 ， 然 后 设置 了 cookie: 





from fLask import make_response 


@app.route('/') 

def index(): 
response = make_response('<h1i>This document carries a cookie!</h1i>') 
response.set_cookie('answer', '42') 
return response 


有 一 种 名 为 重 定 向 的 特殊 响应 类 型 。 这 种 响应 没有 页 面 文档 ， Se 览 器 一 个 新 地 址 用 
以 加 载 新 页 面 。 重 定向 经 常 在 Web 表单 中 使 用 ， 第 4 章 会 进行 介 








重 定向 经 常 使 用 302 状态 码 表示 ， 指 向 的 地 址 由 Location 首部 提供 。 重 定向 响应 可 以 使 用 
3 个 值 形式 的 返回 值 生成 ， 也 可 在 Response 对 象 中 设 定 。 不 过 ， 由 于 使 用 频繁 ，Flask 提 
供 了 redirect() 辅助 函数 ， 用 于 生成 这 种 啊 应 : 

from flask import redirect 

@app.route('/') 


def index(): 
return redirect('http://www.example.com') 


还 有 一 种 特殊 的 响应 由 abort 函数 生成 ， 用 于 处 理 错误 。 在 下 面 这 个 例子 中 ， 如 果 URL 中 
动态 参数 id 对 应 的 用 户 不 存在 ， 就 返回 状态 码 404: 








from fLask import abort 


Qapp.route('/user/<id>') 
def get_user(id): 
user = load_user(id) 
if not user: 
abort(404) 
return '<hi>Hello, %s</h1i>' % user.name 


，abort 不 会 把 控制 权 交 还 给 调用 它 的 国 数 ， 而 是 抛 出 异常 把 控制 权 交 给 Web 服 


o 


注 
务 


:已 、 
口 


绢 淖 


2.6 ”Flask 扩 展 


Flask 被 设计 为 可 扩展 形式 ， 故 而 没有 提供 一 些 重要 的 功能 ， 例 如 数据 库 和 用 户 认证 ， 所 
以 开发 者 可 以 自由 选择 最 适合 程序 的 包 ， 或 者 按 需 求 自行 开发 。 

















社区 成 员 开发 了 大 量 不 同 用 途 的 扩展 ， 如 果 这 还 不 能 满足 需求 ， 你 还 可 使 用 所 有 Python 标 
准 包 或 代码 库 。 为 了 让 你 知道 如 何 把 扩展 整合 到 程序 中 ， 接 下 来 我 们 将 在 hello.py 中 添加 
一 个 扩展 ， 使 用 命令 行 参数 增强 程序 的 功能 。 





使 用 Flask-Script 支 持 命 令 行 选项 
Flask 的 开发 Web 服务 器 支持 很 多 局 动 设置 选项 ， 但 只 能 在 脚本 中 作为 参数 传 给 app.run() 
函数 。 这 种 方式 并 不 十 分 方便 ， 传 递 设置 选项 的 理想 方式 是 使 用 命令 行 参数 。 





Flask-Script 是 一 个 Flask 扩展 ， 为 Flask 程序 添加 了 一 个 命令 行 解析 器 。Flask-Script 自 带 
了 一 组 常用 选项 ， 而 且 还 支持 自 定义 命令 。 





Flask-Script 扩展 使 用 pip 安装 : 


(venv) $ pip install flask-script 
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示例 2-3 显示 了 把 命令 行 解析 功能 添加 到 hello.py 程序 中 时 需要 修改 的 地 方 。 


示例 2-3 hello.py: 使 用 Flask-Script 


from flask.ext.script import Manager 
manager = Manager(app) 


# ... 


if _ name _ == '__main _ 
manager .run() 


专 为 Flask 开发 的 扩展 都 暴 漏 在 flask.ext 命名 空间 下 。Flask-Script 输出 了 一 个 名 为 
Manager 的 类 ， 可 从 flask.ext.script 中 引入 。 




















这 个 扩展 的 初始 化 方法 也 适用 于 其 他 很 多 扩展 : 把 程序 实例 作为 参数 传 给 构造 函数 ， 初 始 
化 主 类 的 实例 。 创 建 的 对 象 可 以 在 各 个 扩展 中 使 用 。 在 这 里 ， 服 务 器 由 manager.run() 启 
动 ， 启 动 后 就 能 解析 命令 行 了 。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 qit checkout 
zc 签 出 程序 的 这 个 版 本 。 














这 样 修改 之 后 ， 程 序 可 以 使 用 一 组 基本 命令 行 选项 。 现 在 运行 hello.py， 会 显示 一 个 用 法 
消息 : 


$ python hello.py 
usage: hello.py [-h] {shell,runserver} ... 


positional arguments: 
{shell,runserver} 





shell 在 Flask 应 用 上 下 文中 运行 Python shell 
runserver 运行 FLask 开发 服务 器 : app.run() 





optional arguments : 
-h, --help 显示 帮助 信息 并 退出 


shell 命令 用 于 在 程序 的 上 下 文中 启动 Python shell 会 话 。 你 可 以 使 用 这 个 会 话 中 运行 维护 
任务 或 测试 ， 还 可 调试 异常 。 


顾名思义 ，runserver 命令 用 来 启动 Web 服务 器 。 运 行 python hello.py runserver 将 以 调 
试 模 式 启 动 Web 服务 器 ， 但 是 我 们 还 有 很 多 选项 可 用 : 


(venv) $ python hello.py runserver --help 

usage: hello.py runserver [-h] [-t HOST] [-p PORT] [--threaded] 
[--processes PROCESSES] [--passthrough-errors] [-d] 
[=r] 














运行 FLask 开发 服务 器 : app.run() 





optional arguments : 
-h, --help 显示 帮助 信息 并 退 
-七 HOST，--host HOST 
-p PORT，--port PORT 
--threaded 
--processes PROCESSES 
--passthrough-errors 
-d,--no-debug 
-T，--no-reLoad 





上 





--host 参数 是 个 很 有 用 的 选项 ， 它 告诉 Web 服务 器 在 哪个 网 络 接口 上 监听 来 自 客户 端的 
连接 。 默 认 情况 下 ，EFlask 开发 Web 服务 器 监听 Locathost 上 的 连接 ， 所 以 只 接受 来 自 服 
务 器 所 在 计算 机 发 起 的 连接 。 下 述 命令 让 Web 服务 器 监听 公共 网 络 接口 上 的 连接 ， 人 允许 同 
网 中 的 其 他 计算 机 连接 服务 器 : 








(venv) $ python hello.py runserver --host 0.0.0.0 
* Running on http://0.0.0.0:5000/ 
* Restarting with reloader 





现在 ，Web 服务 器 可 使 用 http://a.b.c.d:5000/ 网 络 中 的 任 一 台电 脑 进行 访问 ， 其 中 “a.b.c.d” 
是 服务 器 所 在 计算 机 的 外 网 PP 地 址 。 


本 章 介 绍 了 请 求 响应 的 概念 ， 不 过 响应 的 知识 还 有 很 多 。 对 于 使 用 模板 生成 响应 ，Flask 
提供 了 良好 支持 ， 这 是 个 很 重要 的 话题 ， 下 一 章 我 们 还 要 专门 介绍 模板 。 
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要 想 开发 出 易于 维护 的 程序 ， 关 键 在 于 编写 形式 简洁 且 结 构 良 好 的 代码 。 到 目前 为 止 ， 你 
看 到 的 示例 都 太 简 单 ， 无 法 说 明 这 一 点 ， 但 Flask 视图 函数 的 两 个 完全 独立 的 作用 却 被 融 
合 在 了 一 起 ， 这 就 产生 了 一 个 问题 。 


视图 函数 的 作用 很 明确 ， 即 生成 请 求 的 响应 ， 如 第 2 章 中 的 示例 所 示 。 对 最 简单 的 请 求 来 说 ， 
这 就 足够 了 ， 但 一 般 而 言 ， 请 求 会 改变 程序 的 状态 ， 而 这 种 变化 也 会 在 视图 函数 中 产生 。 


例如 ， 用 户 在 网 站 中 注册 了 一 个 新 帐户。 用户 在 表单 中 输入 电子 邮件 地 址 和 密码 ， 然 后 点 
击 提交 按钮 。 服 务 器 接收 到 包含 用 户 输入 数据 的 请 求 ， 然 后 Flask 把 请 求 分 发 到 处 理 注册 
请 求 的 视图 函数 。 这 个 视图 函数 需要 访问 数据 库 ， 添 加 新 有 用户， 然后 生成 响应 回 送 浏览 
器 。 这 两 个 过 程 分 别称 为 业务 逻辑 和 表现 逻辑 。 

把 业务 逻辑 和 表现 逻辑 混在 一 起 会 导致 代码 难以 理解 和 维护 。 假 设 要 为 一 个 大 型 表格 构建 
HTML 代码 ， 表 格 中 的 数据 由 数据 库 中 读 取 的 数据 以 及 必要 的 HTML 字符 串 连 接 在 一 起 。 
把 表现 逻辑 移 到 模板 中 能 够 提升 程序 的 可 维护 性 。 

模板 是 一 个 包含 响应 文本 的 文件 ， 其 中 包含 用 占 位 变量 表示 的 动态 部 分 ， 其 具体 值 只 在 请 
求 的 上 下 文中 才能 知道 。 使 用 真实 值 替换 变量 ， 再 返回 最 终 得 到 的 响应 字符 串 ， 这 

称 为 泻 染 。 为 了 泻 染 模板 ，Flask 使 用 了 一 个 名 为 Jinja2 的 强大 模板 引擎 。 


3.1 Jinja2 模 板 引 擎 


形式 最 简单 的 Jinja2 模板 就 是 一 个 包含 响应 文本 的 文件 。 示 例 3-1 是 一 个 Jinja2 模板 ， 它 
和 示例 2-1 中 index() 视图 函数 的 响应 一 样 。 











































































































示例 3-1 templates/index.html: Jinja2 模板 
<h1>HeLLo WorLd!</h1> 


示例 2-2 中 ， 视 图 函数 user() 返回 的 响应 中 包含 一 个 使 用 变量 表示 的 动态 部 分 。 示 例 3-2 
实现 了 这 个 响应 。 





示例 3-2 templates/user.html: Jinja2 模板 
<hi>Hello, {{ name }}!</h1> 


3.1.1 泻 染 模板 

默认 情况 下 ，Flask 在 程序 文件 夹 中 的 templates 子 文件 夹 中 寻找 模板 。 在 下 一 个 hello.py 
版 本 中 ， 要 把 前 面 定义 的 模板 保存 在 templates 文件 夹 中 ， 并 分 别 命名 为 mdex.html 和 user. 
html。 








程序 中 的 视图 函数 需要 修改 一 下 ， 以 便 泻 染 这 些 模板 。 修 改 方法 参见 示例 3-3。 














示例 3-3 ”hello.py: 渲染 模板 


from flask import Flask, render_template 
# ... 


@app.route('/') 
def index(): 
return render_template('index.html') 


Qapp.route(' /user/<name> ') 
def user(name ) : 
return render_template('user.html', name=name) 


Flask 提供 的 render_template 函数 把 Jinja2 模板 引擎 集成 到 了 程序 中 。render_template 国 
数 的 第 一 个 参数 是 模板 的 文件 各。 随后 的 参数 都 是 键 值 对 ， 表 示 模 板 中 变量 对 应 的 真实 
值 。 在 这 段 代码 中 ， 第 二 个 模板 收 到 一 个 名 为 name 的 变量 。 




















前 例 中 的 name=name 是 关键 字 参 数 ， 这 类 关键 字 参 数 很 常见 ， 但 如 果 你 不 熟悉 它们 的 话 ， 
可 能 会 觉得 迷惑 且 难 以 理解 。 左 边 的 “name” 表 示 参 数 名 ， 就 是 模板 中 使 用 的 占 位 符 ; 碳 
边 的 “name” 是 当前 作用 域 中 的 变量 ， 表 示 同 名 参数 的 值 。 























如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
3a 签 出 程序 的 这 个 版 本 。 

















3.1.2 ”变量 
示例 3-2 在 模板 中 使 用 的 {{ name ]}} 结构 表示 一 个 变量 ， 它 是 一 种 特殊 的 占 位 符 ， 告 诉 模 
板 引 擎 这 个 位 置 的 值 从 浑 染 模板 时 使 用 的 数据 中 获取 。 
Jinja2 能 识别 所 有 类 型 的 变量 ， 甚 至 是 一 些 复杂 的 类 型 ， 例 如 列表 、 字 典 和 对 象 。 在 模板 
中 使 用 变量 的 一 些 示 例如 下 : 

<p>A value from a dictionary: {{ mydict['key'] }}.</p> 

<p>A value from a list: {{ mylist[3] }}.</p> 


<p>A value from a list, with a variable index: {{ mylist[myintvar] }}.</p> 
<p>A value from an object's method: {{ myobj.somemethod() }}.</p> 


可 以 使 用 过 滤器 修改 变量 ， 过 滤器 名 添加 在 变量 名 之 后 ， 中 间 使 用 竖 线 分 隅 。 例 如 ， 下 述 
模板 以 首 字母 大 写 形式 显示 变量 name 的 值 : 


Hello, {{ name|capitalize }} 





表 3-1 列 出 了 Jinja2 提供 的 部 分 常用 过 滤器 。 


表 3-1 Jinja2 变 量 过 滤器 
过 滤器 名 说 明 


















































safe 泻 染 值 时 不 转 义 

capitalize 把 值 的 首 字 母 转换 成 大 写 ， 其 他 字母 转换 成 小 写 
Lower 把 值 转 换 成 小 写 形式 

Upper 把 值 转换 成 大 写 形式 

title 把 值 中 每 个 单词 的 首 字母 都 转换 成 大 写 

trim 把 值 的 首尾 空格 去 掉 

striptags 泻 染 之 前 把 值 中 所 有 的 HTML 标签 都 删 掉 





safe 过 滤器 值得 特别 说 明 一 下 。 上 默认 情况 下 ， 出 于 安全 考虑 ，Jinja2 会 转 义 所 有 变量 。 例 
如 ， 如 果 一 个 变量 的 值 为 '<h1>Hello</h1>' ，Jinja2 会 将 其 泻 染 成 '&Lt;h1&gt;HeLLo&Lt;/ 
hi&gt;' ,浏览 器 能 显示 这 个 hi 元素， 但 不 会 进行 解释 。 很 多 情况 下 需要 显示 变量 中 存储 
的 HTML 代码 ， 这 时 就 可 使 用 safe 过 滤器 。 


仆 、 四 


整 的 过 滤器 列表 可 在 Jinja2 文档 (http://jinja.pocoo.org/docs/templates/#builtin-filters) 中 
看 。 






































de 


在 不 可 信 的 值 上 使 用 safe 过 滤器 ， 例 如 用 户 在 表单 中 输入 的 文本 。 














啼 这 
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3.1.3 控制 结构 
Jinja2 提供 了 多 种 控制 结构 ， 可 用 来 改变 模板 的 泻 染 流程 。 本 节 使 用 简单 的 例子 介绍 其 中 
最 有 用 的 控制 结构 。 


下 面 这 个 例子 展示 了 如 何在 模板 中 使 用 条 件 控制 语句 : 

















{% if user %} 

Hello, {{ user }}! 
{% else %} 

Hello, Stranger! 
{% endif %} 


另 一 种 常见 需求 是 在 模板 中 这 染 一 组 元 素 。 下 例 展示 了 如 何 使 用 for 循环 实现 这 一 需求 : 





<Uls 
{% for comment in comments %} 
<li>{{ comment }}</1li> 
{% endfor %} 
</ul> 





Jinja2 还 支持 宏 。 宏 类 似 于 Python 代码 中 的 函数 。 例 如 : 


{% macro render_comment(comment) %} 
<li>{{ comment }}</li> 
{% endmacro %} 


<ul> 
{% for comment in comments %} 
{{ render_comment(comment) }} 
{% endfor %} 
</ul> 


为 了 重复 使 用 宏 ， 我 们 可 以 将 其 保存 在 单独 的 文件 中 ， 然 后 在 需要 使 用 的 模板 中 导入 : 


{% import 'macros.html' as macros %} 
<ul> 
{% for comment in comments %} 
{{ macros.render_comment(comment) }} 
{% endfor %} 
</ul> 


需要 在 多 处 重复 使 用 的 模板 代码 片段 可 以 写 入 单独 的 文件 ， 再 色 含 在 所 有 模板 中 ， 以 避免 
重复 : 





{% include 'common.html' %} 





另 一 种 重复 使 用 代码 的 强大 方式 是 模板 继承 ， 它 类 似 于 Python 代码 中 的 类 继承 。 首 先 ， 创 
建 一 个 名 为 base.html 的 基 模 板 : 
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<htmL> 
<head> 
{% block head %} 
<title>{% block title %}{% endblock %} - My Application</title> 
{% endblock %} 
</head> 
<body> 
{% block body %} 
{% endblock %} 
</body> 
</html> 


block 标签 定义 的 元 素 可 在 衍生 模板 中 修改 。 在 本 例 中 ， 我 们 定义 了 名 为 head、title 和 
body 的 块 。 广 意 ，titte 包含 在 head 中 。 下 面 这 个 示例 是 基 模 板 的 衍生 模板 : 


{% extends "base.html" %} 
{% block title %}Index{% endblock %} 
{% block head %} 
{{ super() }} 
<style> 
</style> 
{% endblock %} 
{% block body %} 
<hi>Hello, World!</h1i> 
{% endblock %} 





extends 指令 声明 这 个 模板 衍生 自 base.html。 在 extends 指令 之 后 ， 基 模板 中 的 3 个 块 被 
重新 定义 ， 模 板 引擎 会 将 其 插入 适当 的 位 置 。 注 意 新 定义 的 head 块 ， 在 基 模 板 中 其 内 容 不 
是 空 的 ， 所 以 使 用 super() 获取 原来 的 内 容 。 


稍 后 会 展示 这 些 控制 结构 的 具体 用 法 ， 让 你 了 解 一 下 它们 的 工作 原理 


3. 





0° 


2 使 用 Flask-Bootstrap 集 成 Twitter Bootstrap 


Bootstrap (http://getbootstrap.com/) 是 Twitter 开发 的 一 个 开源 框架 ， 它 提供 的 用 户 界面 组 
件 可 用 于 创建 整洁 且 具 有 吸引 力 的 网 页 ， 而 且 这 些 网 页 还 能 兼容 所 有 现代 Web 浏览 器 。 














Bootstrap 是 客户 端 框架 ， 因 此 不 会 直接 涉及 服务 器 。 服 务 器 需要 做 的 只 是 提供 引用 了 
Bootstrap 层 合 样式 表 (CSS) 和 JavaScript 文 件 的 HTML 响应 ， 并 在 HTML、CSS 和 
JavaScript 代码 中 实例 化 所 需 组 件 。 这 些 操作 最 理想 的 执行 场所 就 是 模板 。 
































要 想 在 程序 中 集成 Bootstrap， 显 然 要 对 模板 做 所 有 必要 的 改动 。 不 过 ， 更 简单 的 方法 是 
使 用 一 个 名 为 Flask-Bootstrap 的 Flask 扩展 ， 简 化 集成 的 过 程 。Flask-Bootstrap 使 用 pip 





安装 : 


(venv) $ pip install flask-bootstrap 
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Flask 扩展 一 般 都 在 创建 程序 实例 时 初始 化 。 示 例 3-4 是 Flask-Bootstrap 的 初始 化 方法 。 





示例 3-4 _ hello.py: 初始 化 Flask-Bootstrap 


from fLask.ext.bootstrap import Bootstrap 
# ... 
bootstrap = Bootstrap(app) 


和 第 2 章 中 的 Flask-Script 一 样 ，Flask-Bootstrap 也 从 flask.ext 命名 空间 中 导入 ， 然 后 把 
程序 实例 传 入 构造 方法 进行 初始 化 。 





初始 化 Flask-Bootstrap 之 后 ， 就 可 以 在 程序 中 使 用 一 个 包含 所 有 Bootstrap 文件 的 基 模 板 。 
这 个 模板 利用 Jinja2 的 模板 继承 机 制 ， 让 程序 扩展 一 个 具有 基本 页 面 结 构 的 基 模 板 ， 其 中 
就 有 用 来 引入 Bootstrap 的 元 素 。 示 例 3-5 是 把 user.html 改写 为 衍生 模板 后 的 新 版 本 。 




















示例 3-5 templates/user.html: 使 用 Flask-Bootstrap 的 模板 
{% extends "bootstrap/base.html" %} 


{% block title %}FLasky{% endblock %} 


{% block navbar %} 
<div class="navbar navbar-inverse" role="navigation"> 
<div class="container"> 
<div class="navbar-header"> 
<button type="button" class="navbar-toggle" 
data-toggle="collapse" data-target=".navbar-collapse"> 
<span class="sr-only">Toggle navigation</span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
</button> 
<a class="navbar-brand" href="/">Flasky</a> 
</div> 
<div class="navbar-collapse collapse"> 
<ul class="nav navbar-nav"> 
<li><a href="/">Home</a></li> 
</ul> 
</div> 
</div> 
</div> 
{% endblock %} 


{% block content %} 
<div class="container"> 
<div class="page-header"> 
<hi>Hello, {{ name }}!</h1> 
</div> 
</div> 
{% endblock %} 


Jinja2 中 的 extends 指令 从 Flask-Bootstrap 中 导入 bootstrap/base.html， 从 而 实现 模板 继 
承 。Flask-Bootstrap 中 的 基 模 板 提 供 了 一 个 网 页 框架 ， 引 入 了 Bootstrap 中 的 所 有 CSS 和 
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JavaScript 文件 。 


基 模 板 中 定义 了 可 在 衍生 模板 中 重 定义 的 块 。bLock 和 endblock 指令 定义 的 块 中 的 内 容 可 


添加 到 基 模 板 中 。 


上 面 这 个 user.html 模板 定义 了 3 个 块 ， 分 别名 为 title、navbar 和 content。 这 些 块 都 是 














基 模 板 提供 的 ， 可 在 衍生 模板 中 重新 定义 。title 块 的 作用 很 明显 ， 其 中 的 内 容 会 H 





现在 


演 染 后 的 HTML 文档 头 部 ， 放 在 <title> 标签 中 。navbar 和 content 这 两 个 块 分 别 表 示 页 





面 中 的 导航 条 和 主体 内 容 。 


在 这 个 模板 中 ，navbar 块 使 用 Bootstrap 组 件 定义 了 一 个 简单 的 导航 条 。content 块 中 有 个 
<div> 容器 ， 其 中 包含 一 个 页 面 头 部 。 之 前 版 本 的 模板 中 的 欢迎 信息 ， 现 在 就 放 在 这 个 页 





而 头 部 。 改 动 之 后 的 程序 如 图 3-1 所 示 。 

















好 的 学 习 资 源 ， 有 很 多 可 以 直接 复制 粘贴 的 示例 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3b 签 出 程序 的 这 个 版 本 。Bootstrap 官方 文档 (http://getbootstrap.com/) 是 很 





eoe Flasky 


Hello, Dave! 
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3-1 Twitter Bootstrap 模板 


Flask-Bootstrap 的 base.html 模板 还 定义 了 很 多 其 他 块 ， 都 可 在 衍生 模板 中 使 用 。 表 3-2 列 














出 了 所 有 可 用 的 快 。 
表 3-2 ”Flask-Bootstrap 基 模板 中 定义 的 块 
块 名 | 说明 
doc 整个 HTML 文档 
html_attribs <html> 标签 的 属性 
html <html> 标签 中 的 内 容 
head <head> 标签 中 的 内 容 
title <title> 标签 中 的 内 容 











模板 



































块 名 说 明 

metas 一 组 <meta> 标签 

styles 层 登 样式 表 定 义 
body_attribs <body> 标签 的 属性 

body <body> 标签 中 的 内 容 
navbar 用 户 定义 的 导航 条 
Content 用 户 定义 的 页 面 内 容 
scripts 文档 底部 的 JavaScript 声明 





表 3-2 中 的 很 多 块 都 是 Flask-Bootstrap 自用 的 ， 如 果 直 接 重 定义 可 能 会 导致 一 些 问题 。 例 
如 ，Bootstrap 所 需 的 文件 在 styles 和 scripts 块 中 声明 。 如 果 程 序 需 要 向 已 经 有 内 容 的 块 
中 添加 新 内 容 ， 必 须 使 用 Jinja2 提供 的 super() 国 数 。 例 如 ， 如 果 要 在 衍生 模板 中 添加 新 
的 JavaScript 文件 ， 需 要 这 么 定义 scripts 块 : 














{% block scripts %} 
{{ super() }} 


<script type="text/javascript" src="my-script.js"></script> 
{% endblock %} 


3.3” 自 定义 错误 页 


如 果 你 在 浏览 器 的 地 址 栏 中 输入 了 不 可 用 的 路 由 ， 那 么 会 显示 一 个 状态 码 为 404 的 错误 页 
面 。 现 在 这 个 错误 页 面 太 简陋 、 平 良 ， 而 且 样 式 和 使 用 了 Bootstrap 的 页 面 不 一 致 。 




















像 常规 路 由 一 样 ，Flask 允许 程序 使 用 基于 模板 的 自 定义 错误 页 面 。 最 常见 的 错误 代码 有 
两 个 : 404， 客 户 端 请 求 未 知 页 面 或 路 由 时 显示 ; 500， 有 未 处 理 的 异常 时 显示 。 为 这 两 个 
错误 代码 指定 自 定 义 处 理 程序 的 方式 如 示例 3-6 所 示 。 








示例 3-6 hello.py: 自 定义 错误 页 面 
@app.errorhandler(404) 
def page_not_found(e): 
return render_template('404.html'), 404 


@app.errorhandler(500) 
def internal_server_error(e): 
return render_template('500.html'), 500 














和 视图 函数 一 样 ， 错 误 处 理 程序 也 会 返回 响应 。 它 们 还 返回 与 该 错误 对 应 的 数字 状态 码 。 

















错误 处 理 程序 中 引用 的 模板 也 需要 编写 。 这 些 模板 应 该 和 常规 页 面 使 用 相同 的 布局 ， 因 此 
要 有 一 个 导航 条 和 显示 错误 消息 的 页 面 头 部 。 



































编写 这 些 模 板 最 直观 的 方法 是 复制 templates/user.html， 分 别 创建 templates/404.html 和 
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templates/500.html， 然 后 把 这 两 个 文件 中 的 页 面 头 部 元 素 改 为 相应 的 错误 消息 。 但 这 种 方 











法 会 带 来 很 多 重复 劳动 。 























基 








Jinja2 的 模板 继承 机 制 可 以 帮助 我 们 解决 这 一 问题 。Flask-Bootstrap 提供 了 一 个 具有 页 画 





本 布局 的 基 模 板 ， 同 样 ， 程 序 可 以 定义 一 个 具有 更 完整 页 面 布 局 的 基 模 板 ， 其 中 包含 导航 
条 ， 而 页 面 内 容 则 可 留 到 衍生 模板 中 定义 。 示 例 3-7 展示 了 templates/base.html 的 内 容 ， 这 
是 一 个 继承 自 bootstrap/base.html 的 新 模板 ， 其 中 定义 了 导航 条 。 这 个 模板 本 身 也 可 作为 其 





他 模板 的 基 模 板 ， 例 如 templates/user.html、templates/404.html 和 templates/500.html。 


示例 3-7 ”templates/base.html: 包含 导航 条 的 程序 基 模 板 
{% extends "bootstrap/base.html" %} 


{% block title %}FLasky{% endblock %} 


{% block navbar %} 
<div class="navbar navbar-inverse" role="navigation"> 
<div class="container"> 
<div class="navbar-header"> 
<button type="button" class="navbar-toggle" 
data-toggle="collapse" data-target=".navbar-collapse"> 
<span class="sr-only">Toggle navigation</span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
<span class="icon-bar"></span> 
</button> 
<a Class="navbar-brand" href="/">Flasky</a> 
</div> 
<div class="navbar-collapse collapse"> 
<ul class="nav navbar-nav "> 
<li><a href="/">Home</a></li> 
</ul> 
</div> 
</div> 
</div> 
{% endblock %} 


{% block content %} 
<div class="container"> 
{% block page_content %}{% endblock %} 
</div> 
{% endblock %} 


这 个 模板 的 content 块 中 只 有 一 个 <div> 容器 ， 其 中 包含 了 一 个 名 为 page_content 的 新 的 


空 块 ， 块 中 的 内 容 由 衍生 模板 定义 。 











现在 ， 程 序 使 用 的 模板 继承 自 这 个 模板 ， 而 不 直接 继承 自 Flask-Bootstrap 的 基 模板 。 通 过 


继承 templates/base.html 模板 编写 自 定义 的 404 错误 页 面 很 简单 ， 如 示例 3-8 所 示 。 
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示例 3-8 templates/404.html: 使 用 模板 继承 机 制 自 定义 404 错误 页 面 
{% extends "base.html" %} 











{% block title %}FLasky - Page Not Found{% endblock %} 


{% block page_content %} 
<div class="page-header"> 
<h1>Not Found</h1> 

</div> 
{% endblock %} 











错误 页 面 在 浏览 器 中 的 显示 效果 如 图 3-2 所 示 。 








eee Flasky - Page Not Found 


<a> | [从] [十 | @ localhost 5000 3 [©@)| 














3-2” 自 定义 的 404 错误 页 面 


templates/user.html 现在 可 以 通过 继承 这 个 基 模 板 来 简化 内 容 ， 如 示例 3-9 所 示 。 





示例 3-9 templates/user.html: 使 用 模板 继承 机 制 简化 页 面 模板 
{% extends "base.html" %} 


{% block title %}Flasky{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<hi>Hello, {{ name }}!</h1> 

</div> 

{% endblock %} 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3c 签 出 程序 的 这 个 版 本 。 

















3.4 ”链接 
任何 具有 多 个 路 由 的 程序 都 需要 可 以 连接 不 同 页 面 的 链接 ， 例 如 导航 条 


在 模板 中 直接 编写 简单 路 由 的 URL 链接 不 难 ， 但 对 于 包含 可 变 部 分 的 动态 路 由 ， 在 模板 
中 构建 正确 的 URL 就 很 困难 。 而 且 ， 直 接 编写 URL 会 对 代码 中 定义 的 路 由 产生 不 必要 的 
依赖 关系 。 如 果 重 新 定义 路 由 ， 模 板 中 的 链接 可 能 会 失效 。 















































为 了 避免 这 些 问 题 ，Flask 提供 了 url_for() 辅助 函数 ， 它 可 以 使 用 程序 URL 映射 中 保存 
的 信息 生成 URL。 


url_for() 函数 最 简单 的 用 法 是 以 视图 函数 名 (或 者 app.add_url_route() 定义 路 由 时 使 用 

端点 名 ) 作为 参数 ， 返 回 对 应 的 URL。 例 如 ， 在 当前 版 本 的 hello.py 程序 中 调用 url_ 
ee 得 到 的 结果 是 /。 调 用 url_for('index'，_external=True) 返回 的 则 是 绝对 地 
址 ， 在 这 个 示例 中 是 http://localhost:5000/。 





生成 连接 程序 内 不 同 路 由 的 链接 时 ， 使 用 相对 地 址 就 足够 了 。 如 果 要 生成 在 
浏览 器 之 外 使 用 的 链接 ， 则 必须 使 用 绝对 地 址 ， 例 如 在 电子 邮件 中 发 送 的 
链接 。 











使 用 url_for() 生成 动态 地 址 时 ， 将 动态 部 分 作为 关键 字 参 数 传 入 。 例 如 ，url_for 
('user'，name='john'，_external=True) 的 返回 结果 是 http://localhost:5000/user/john。 





传人 url_for() 的 关键 字 参 数 不 仅 限于 动态 路 由 中 的 参数 。 函 数 能 将 任何 额外 参数 添加 到 
查询 字符 串 中 。 例 如 ，url_for('index'，page=2) 的 返回 结果 是 /?page=2。 


3.5 ”静态 文件 


Web 程序 不 是 仅 由 Python 代码 和 模板 组 成 。 大 多 数 程序 还 会 使 用 静态 文件 ， 例 如 HTML 
代码 中 引用 的 图 片 、JavaScript 源码 文件 和 CSS。 


你 可 能 还 记得 在 第 2 章 中 检查 hello.py 程序 的 URL 映射 时 ， 其 中 有 一 个 static 路 由 。 
这 是 因为 对 静态 文件 的 引用 被 当成 一 个 特殊 的 路 由 ， 即 /static/<filename>。 例 如 ， 调 用 


url_for('static', filename='css/styles.css'，_external=True) 得 到 的 结果 是 http:// 









































localhost:S000/static/css/styles.css。 


默认 设置 下 ，Flask 在 程序 根 目录 中 名 为 static 的 子 目录 中 寻找 静态 文件 。 如 果 需 要 ， 可 在 
static 文件 夹 中 使 用 子 文件 夹 存放 文件 。 服务器 收 到 前 面 那个 URL 后 ， 会 生成 一 个 响应 ， 
包含 文件 系统 中 static/css/styles.css 文件 的 内 容 。 
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示例 3-10 展示 了 如 何在 程序 的 基 模 板 中 放置 favicon.ico 图 标 。 这 个 图 标 会 显示 在 训 览 器 的 
地 址 栏 中 。 























示例 3-10 templates/base.html1: 定义 收藏 夹 图 标 
{% block head %} 
{{ super() }} 
<Link rel="shortcut icon" href="{{ url_for('static', filename = 'favicon.ico') }}" 
type="image/x-icon"> 
<link rel="icon" href="{{ url_for('static', filename = 'favicon.ico'’) }}" 


type="image/x-icon"> 
{% endblock %} 


图 标的 声明 会 插入 head 块 的 末尾 。 注 意 如 何 使 用 super() 保留 基 模 板 中 定义 的 块 的 原始 
内 容 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3d 签 出 程序 的 这 个 版 本 。 














3.6 ”使 用 Flask-Moment 本 地 化 日 期 和 时 间 
如 果 Web 程序 的 用 户 来 自 世 界 各 地 ， 那 么 处 理 日 期 和 时 间 可 不 是 一 个 简单 的 任务 。 


服务 器 需要 统一 时 间 单 位 ， 这 和 用 户 所 在 的 地 理 位 置 无 关 ， 所 以 一 般 使 用 协调 世界 时 
(Coordinated Universal Time，UTC) 。 不 过 用 户 看 到 UTC 格式 的 时 间 会 感到 困惑 ， 他 们 更 
希望 看 到 当地 时 间 ， 而 且 采 用 当地 惯用 的 格式 。 









































要 想 在 服务 器 上 只 使 用 UTC 时间， 一 个 优雅 的 解决 方案 是 ， 把 时 间 单 位 发 送 给 Web 浏览 
器 ， 转 换 成 当地 时 间 ， 然 后 泻 染 。Web 浏览 器 可 以 更 好 地 完成 这 一 任务 ， 因 为 它 能 获取 用 
户 电 脑 中 的 时 区 和 区 域 设置 。 























有 一 个 使 用 JavaScript 开发 的 优秀 客户 端 开源 代码 库 ， 名 为 moment.js (http://momentjs. 
com/)， 它 可 以 在 浏览 器 中 泻 染 日 期 和 时 间 。Flask-Moment 是 一 个 Flask 程序 扩展 ， 能 把 
moment.js 集成 到 Jinja2 模板 中 。Flask-Moment 可 以 使 用 pip 安装 : 





(venv) $ pip install flask-moment 
这 个 扩展 的 初始 化 方法 如 示例 3-11 所 示 。 


示例 3-11 hello.py: 初始 化 Flask-Moment 


from flask.ext.moment import Moment 
moment = Moment(app) 





除了 moment.js，Flask-Moment 还 依赖 jquery.js。 要 在 HTML 文档 的 某 个 地 方 引 入 这 两 个 
库 ， 可 以 直接 引入 ， 这 样 可 以 选择 使 用 哪个 版 本 ,也 可 使 用 扩展 提供 的 辅助 函数 ， 从 内 容 
分 发 网 络 (Content Delivery Network, CDN) 中 引入 通过 测试 的 版 本 。 Bootstrap 已 经 3| 入 
了 jqueryjs， 因 此 只 需 引 入 momentjs 即 可 。 示 例 3-12 展示 了 如 何在 基 模板 的 scripts 块 
中 引入 这 个 库 。 

















示例 3-12 templates/base.html: 引入 moment.js 库 


{% block scripts %} 
{{ super() }} 


{{ moment.include_ moment() }} 
{% endblock %} 


为 了 处 理 时 间 戳 ，Flask-Moment 向 模板 开放 了 moment 类 。 示 例 3-13 中 的 代码 把 变量 
current_time 传 入 模板 进行 泻 染 。 





示例 3-13 ”hello.py: 加 入 一 个 datetime 变量 
from datetime import datetime 
@app.route('/') 
def index(): 


return render_template('index.html', 
current_ time=datetime.utcnow()) 


示例 3-14 展示 了 如 何在 模板 中 渲染 current_time。 





代码 3-14 ”templates/index.html: 使 用 Flask-Moment 演 染 时 间 稚 


<p>The local date and time is {{ moment(current time).format('LLL') }}.</p> 
<p>That was {{ moment(current_time).fromNow(refresh=True) }}</p> 





format('LLL') 根据 客户 端 电 脑 中 的 时 区 和 区 域 设置 演 染 日 期 和 时 间 。 参 数 决 定 了 泻 染 的 方 
式 ，'L' 到 'LLLL' 分 别 对 应 不 同 的 复杂 度 。format() 函数 还 可 接受 自 定义 的 格式 说 明 符 。 








第 二 行 中 的 fromNow() 泻 染 相对 时 间 蕉 ， 而 且 会 随 着 时 间 的 推移 自动 刷新 显示 的 时 间 。 这 
个 时 间 惟 最 开始 显示 为 “a few seconds ago”"， 但 指定 refresh 参数 后 ， 其 内 容 会 随 着 时 
间 的 推移 而 更 新 。 如 果 一 直 竺 在 这 个 页 面 ， 几 分 钟 后 ， 会 看 到 显示 的 文本 变 成 “a minute 


ag0”“2 minutes ago” 等 。 




















如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
3e 签 出 程序 的 这 个 版 本 。 





Flask-Moment 实现 了 momentjs 中 的 format()、fromNow()、fromTime()、calendar()、vaLueof() 
和 unix() 方法 。 你 可 查阅 文档 (http:/momentjs.com/docs/#/displaying/) 学 习 momentjs 提供 的 全 
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部 格式 化 选项 。 











Flask-Monet 假定 服务 器 端 程序 处 理 的 时 间 惟 是 “纯正 的 ”datetime 对 象 ， 
且 使 用 UTC 表示 。 关 于 纯正 和 细致 的 日 期 和 时 间 对 象 :的 说 明 ， 请 陪读 标准 
库 中 datetime 包 的 文档 (https://docs.python.org/2/library/datetime.html) 。 





Flask-Moment 泻 染 的 时 间 惟 可 实现 多 种 语言 的 本 地 化 。 语 言 可 在 模板 中 选择 ， 把 语言 代码 
传 给 Lang() 函数 即 可 : 


{{ moment.lang('es') }} 





使 用 本 章 介绍 的 技术 ， 你 应 该 能 为 程序 编写 出 现代 化 且 用 户 友好 的 网 页 。 下 一 章 将 介绍 本 
章 没有 涉及 的 一 个 模板 功能 ， 即 如 何 通过 Web 表单 和 用 户 交 互 。 





译注 1: 纯正 的 时 间 惟 ， 英 文 为 navie time， 指 不 包含 时 区 的 时 间 戳 ， 细 致 的 时 间 戳 ， 英 文 为 aware time， 
间 包 含 时 区 的 时 间 戳 。 
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第 3 章 


第 4 章 


Web 表 单 





第 2 章 中 介绍 的 请 求 对 象 包含 客户 端 发 出 的 所 有 请 求 信息 。 其 中 ，request.fornm 能 获取 
POST 请 求 中 提交 的 表单 数据 。 


尽管 Flask 的 请 求 对 象 提供 的 信息 足够 用 于 处 理 Web 表单 ， 但 有 些 任 务 很 单调 ， 而 且 要 重 
复 操作 。 比 如 ， 生 成 表单 的 HTML 代码 和 验证 提交 的 表单 数据 。 




















Flask-WTF (http://pythonhosted.org/Flask-WTF/) 扩展 可 以 把 处 理 Web 表单 的 过 程 变 成 一 
种 愉悦 的 体验 。 这 个 扩展 对 独立 的 WTForms (http://wtforms.simplecodes.com) 包 进 行 了 包 
装 ， 方 便 集 成 到 Flask 程序 中 。 





Flask-WTF 及 其 依赖 可 使 用 pip 安装 : 


(venv) $ pip install flask-wtf 


4.1 跨 站 请 求 伪 造 保 护 


默认 情况 下 ，Flask-WTF 能 保护 所 有 表单 免 受 跨 站 请 求 伪 造 (Cross-Site Request Forgery， 
CSRF) 的 攻击 。 恶 意 网 站 把 请 求 发 送 到 被 攻击 者 已 登录 的 其 他 网 站 时 就 会 引发 CSRF 攻击 。 


为 了 实现 CSRF 保护 ，Flask-WTF 需要 程序 设置 一 个 密 钥 。Flask-WTF 使 用 这 个 密 钥 生 成 
加 密令 牌 ， 再 用 令 牌 验证 请 求 中 表单 数据 的 真 食 。 设 置 密 钥 的 方法 如 示例 4-1 所 示 。 








示例 4-1 hello.py: 设置 Flask-WTF 


app = Flask(__name_ ) 
app.config['SECRET_KEY'] = 'hard to guess string' 
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app.config 字典 可 用 来 存储 框架 、 扩 展 和 程序 本 身 的 配置 变量 。 使 用 标准 的 字典 句法 就 能 
把 配置 值 添加 到 app.config 对 象 中 。 这 个 对 象 还 提供 了 一 些 方法 ， 可 以 从 文件 或 环境 中 导 
入 配置 值 。 





SECRET_KEY 配置 变量 是 通用 密 钥 ， 可 在 Flask 和 多 个 第 三 方 扩 展 中 使 用 。 如 其 名 所 示 ， 加 
密 的 强度 取决 于 变量 值 的 机 密 程度 。 不 同 的 程序 要 使 用 不 同 的 密 钥 ， 而 且 要 保证 其 他 人 不 
知道 你 所 用 的 字符 串 。 








为 了 增强 安全 性 ， 密 钥 不 应 该 直接 写 入 代码， 而 要 保存 在 环境 变量 中 。 这 一 
技术 会 在 第 7 章 介绍 。 





4.2 ”表单 类 


使 用 Flask-WTF 时 ， 每 个 Web 表单 都 由 一 个 继承 自 Forn 的 类 表示 。 这 个 类 定义 表单 中 的 
一 组 字段 ， 每 个 字段 都 用 对 象 表示 。 字 段 对 象 可 附属 一 个 或 多 个 验证 函数 。 验 证 国 数 用 来 
验证 用 户 提交 的 输入 值 是 否 符合 要 求 。 


示例 4-2 是 一 个 简单 的 Web 表单， 包含 一 个 文本 字段 和 一 个 提交 按钮 。 





示例 4-2 hello.py: 定义 表单 类 
from flask.ext.wtf import Form 
from wtforms import StringField, SubmitField 
from wtforms.validators import Required 


class NameForm(Form): 
name = StringField('What is your name?', validators=[Required()]) 
submit = SubmitField('Submit') 


这 个 表单 中 的 字段 都 定义 为 类 变量 ， 类 变量 的 值 是 相应 字段 类 型 的 对 象 。 在 这 个 示例 中 ， 
NameForm 表单 中 有 一 个 名 为 name 的 文本 字段 和 一 个 名 为 submit 的 提交 按钮 。StringField 
类 表示 属性 为 type="text" 的 <input> 元 素 。SubmitFietLd 类 表示 属性 为 type="submit" 的 
<input> 元 素 。 字 有 段 构造 函数 的 第 一 个 参数 是 把 表单 演 染 成 HTML 时 使 用 的 标号 。 


StringField 构造 国 数 中 的 可 选 参数 validators 指定 一 个 由 验证 函数 组 成 的 列表 ， 在 接受 
用 户 提交 的 数据 之 前 验证 数据 。 验 证 函数 Required() 确保 提交 的 字段 不 为 空 。 








Form 基 类 由 Flask-WTF 扩展 定义 ， 所 以 从 fLask.ext.wtf 中 导入 。 字 段 和 验 
证 函数 却 可 以 直接 从 WTForms 包 中 导入 。 








WTForms 支持 的 HTML 标准 字段 如 表 4-1 所 示 。 




















表 4-1 WTForms 支 持 的 HTML 标 准 字段 

字段 类 型 说 明 

StringField 文本 字段 

TextAreaField 多 行文 本 字段 

passwordField 密码 文本 字段 

HiddenField 隐藏 文本 字段 

DateField 文本 字段 ， 值 为 datetime.date 格式 
DateTimeField 文本 字段 ， 值 为 datetime.datetime 格式 
IntegerField 文本 字段 ， 值 为 整数 

DecimalField 文本 字段 ， 值 为 decimal.Decimal 
FloatField 文本 字段 ， 值 为 浮 点 数 
BooleanField 复 选 框 ， 值 为 True 和 False 
RadioField 一 组 单 选 框 

SelectField 下 拉 列 表 

SelectMultipleField 下 拉 列 表 ， 可 选择 多 个 值 
FileField 文件 上 传 字段 

SubmitField 表单 提交 按钮 

FormField 把 表单 作为 字段 嵌入 另 一 个 表单 
FieldList 一 组 指定 类 型 的 字段 





WTForms 内 建 的 验证 函数 如 表 4-2 所 示 。 


表 4-2 WTForms 验 证 函数 






































验证 函数 说 明 

Email 验证 电子 邮件 地 址 

EqualTo 比较 两 个 字段 的 值 ， 常 用 于 要 求 输 入 两 次 密码 进行 确认 的 情况 
IPAddress 验证 IPv4 网 络 地 址 

Length 验证 输入 字符 串 的 长 度 
NumberRange 验证 输入 的 值 在 数字 范围 内 
Optional 无 输入 值 时 跳 过 其 他 验证 函数 
Required 确保 字段 中 有 数据 

Regexp 使 用 正则 表达 式 验证 输入 值 
URL 验证 URL 

Anyof 确保 输入 值 在 可 选 值 列表 中 
NoneOf 确保 输入 值 不 在 可 选 值 列表 中 








4.3 把 表单 泻 染 成 HTML 


表单 字段 是 可 调用 的 ， 在 模板 中 调用 后 会 泻 染 成 HTML。 假 设 视 图 函数 把 一 个 NameForn 实 








例 通过 参数 form 传人 模板 ， 在 模板 中 可 以 生成 一 个 简单 的 表单 ， 如 下 所 示 : 


<form method="POST"> 
{{ form.hidden_tag() }} 
{{ form.name.LabeL }} {{ form.name() }} 
{{ form.submit() }} 

</form> 





当然 ， 这 个 表单 还 很 简陋 。 要 想 改 进 表单 的 外 观 ， 可 以 把 参数 传 入 泻 染 字段 的 函数 ， 传 入 
的 参数 会 被 转换 成 字段 的 HTML 属性。 例如， 可 以 为 字段 指定 id 或 class 属性 ， 然 后 定 
义 CSS 样式 : 
<form method="POST"> 
{{ form.hidden_tag() }} 
{{ form.name.label }} {{ form.name(id='my-text-field') }} 


{{ form.submit() }} 
</form> 





即便 能 指定 HTML 属性 ， 但 按照 这 种 方式 泻 染 表单 的 工作 量 还 是 很 大 ， 所 以 在 条 件 允 许 的 
情况 下 最 好 能 使 用 Bootstrap 中 的 表单 样式 。Flask-Bootstrap 提供 了 一 个 非常 高 端的 辅助 函 
数 ， 可 以 使 用 Bootstrap 中 预先 定义 好 的 表单 样式 泻 染 整个 Flask-WTF 表单 ， 而 这 些 操作 
只 需 一 次 调用 即 可 完成 。 使 用 Flask-Bootstrap， 上 述 表 单 可 使 用 下 面 的 方式 演 染 : 


{% import "bootstrap/wtf.html" as wtf %} 
{{ wtf.quick_ form(form) }} 

















import 指令 的 使 用 方法 和 普通 Python 代码 一 样 ， 允 许 导 入 模板 中 的 元 素 并 用 在 多 个 模板 
中 。 导 入 的 bootstrap/wtf.html 文件 中 定义 了 一 个 使 用 Bootstrap 演 染 Falsk-WTF 表单 对 象 
的 辅助 函数 。wtf.quick_form() 函数 的 参数 为 Flask-WTF 表单 对 象 ， 使 用 Bootstrap 的 默认 
样式 演 染 传人 的 表单 。hello.py 的 完整 模板 如 示例 4-3 所 示 。 











示例 4-3 templates/index.html: 使 用 Flask-WTF 和 Flask-Bootstrap 演 染 表单 
{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 
{% block title %}Flasky{% endblock %} 


{% block page_content %} 
<div class="page-header"> 
<hi>Hello, {% if name %}{{ name }}{% else %}Stranger{% endif %}!</h1i> 
</div> 
{{ wtf.quick_form(form) }} 
{% endblock %} 


模板 的 内 容 区 现在 有 两 部 分 。 第 一 部 分 是 页 面 头 部 ， 显 示 欢 迎 消息 。 这 里 用 到 了 一 个 模板 
条 件 语句 。Jinja2 中 的 条 件 语句 格式 为 {% if condition %}...{% else %}...{% endif %}。 
如 果 条 件 的 计算 结果 为 True， 那 么 泻 染 if 和 else 指令 之 间 的 值 。 如 果 条 件 的 计算 结果 为 
False， 则 泻 染 eLse 和 endif 指令 之 间 的 值 。 在 这 个 例子 中 ， 如 果 没 有 定义 模板 变量 name， 








则 会 浑 染 字 符 串 “Hello, Stranger!”。 内 容 区 的 第 二 部 分 使 用 wtf.quick_form() 函数 演 染 
NameFornm 对 象 。 


4.4 在 视图 函数 中 处 理 表 单 


在 新 版 hello.py 中 ， 视 图 函数 index() 不 仅 要 泻 染 表单 ， 还 要 接收 表单 中 的 数据 。 示 例 4-4 
是 更 新 后 的 index() 视图 函数 。 























加 





示例 4-4 _ hello.py: 路 由 方法 
@app.route('/', methods=['GET', 'POST']) 
def index(): 
name = None 
form = NameForm() 
if form.validate_on_submit(): 
name = form.name.data 
form.name.data = "" 
return render_template('index.html', form=form, name=name) 


app.route 修饰 器 中 添加 的 methods 参数 告诉 Flask 在 URL 映射 中 把 这 个 视图 函数 注册 为 
GET 和 POST 请 求 的 处 理 程序 。 如 果 没 指定 methods 参数 ， 就 只 把 视图 函数 注册 为 GET 请 求 
的 处 理 程序 。 


把 POST 加 入 方法 列表 很 有 必要 ， 因 为 将 提交 表单 作为 P05T 请 求 进行 处 理 更 加 便利 。 表 单 
也 可 作为 GET 请 求 提交 ， 不 过 GET 请 求 没 有 主体 ， 提 交 的 数据 以 查询 字符 串 的 形式 附加 到 
URL 中 ， 可 在 浏览 器 的 地 址 栏 中 看 到 。 基 于 这 个 以 及 其 他 多 个 原因 ， 提 交 表单 大 都 作为 
POST 请 求 进行 处 理 。 

































































局 部 变量 name 用 来 存放 表单 中 输入 的 有 效 名 字 ， 如 果 没 有 输入 ， 其 值 为 None。 如 上 述 代 
码 所 示 ， 在 视图 函数 中 创建 一 个 NameForm 类 实例 用 于 表示 表单 。 提 交 表 单 后 ， 如 果 数据 能 
被 所 有 验证 函数 接受 ， 那 么 validate_on_submit() 方法 的 返回 值 为 True， 否则 返回 Fatse。 
这 个 函数 的 返回 值 决定 是 重新 泻 染 表单 还 是 处 理 表单 提交 的 数据 。 


用 户 第 一 次 访问 程序 时 ， 服 务 器 会 收 到 一 个 没有 表单 数据 的 GET 请 求 ， 所 以 validate_on_ 
submit() 将 返回 False。if 语句 的 内 容 将 被 跳 过 ， 通 过 泻 染 模板 处 理 请 求 ， 并 传人 表单 对 
象 和 值 为 None 的 name 变量 作为 参数 。 用 户 会 看 到 浏览 器 中 显示 了 一 个 表单 。 


用 户 提交 表单 后 ， 服 务 器 收 到 一 个 包含 数据 的 PosT 请 求 。validate_on_submit() 会 调用 
name 字段 上 附属 的 Required() 验证 函数 。 如 果 名 字 不 为 空 ， 就 能 通过 验证 ，validate_on_ 
submit() 返回 True。 现 在 ， 用 户 输入 的 名 字 可 通过 字段 的 data 属性 获取 。 在 if 语句 中 ， 
把 名 字 赋 值 给 局 部 变量 name， 然 后 再 把 data 属性 设 为 空 字符 串 ， 从 而 清空 表单 字段 。 最 
后 一 行 调用 render_template() 函数 泻 染 模板 ,但 这 一 次 参数 name 的 值 为 表单 中 输入 的 名 
字 ， 因 此 会 显示 一 个 针对 该 用 户 的 欢迎 消息 。 
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4a 签 出 程序 的 这 个 版 本 。 














如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 


图 4-1 是 用 户 首次 访问 网 站 时 浏览 器 显示 的 表单 。 用 户 提交 名 字 后 ， 程 序 会 生成 一 个 针对 
该 用 户 的 欢迎 消息 。 欢 迎 消息 下 方 还 是 会 显示 这 个 表单 ， 以 便 用 户 输入 新 名 字 。 


示 了 此 时 程序 的 样子 。 














入 | 








4-2 显 








What is your name? 


Submit 





@ee Flasky 





Hello, Stranger! 




















4-1 Flask-WTF Web 表单 





如 果 用 户 提交 表单 之 前 没有 输入 名 字 ，Required() 验证 函数 会 捕获 这 个 错误 ， 如 


示 。 注 意 一 下 扩展 自动 提供 了 多 少 功能 。 这 说 明 像 Fask-WTE 条 





良好 的 扩展 能 让 程序 具有 强大 的 功能 。 




















及 











4-3 所 


中 Flask-Bootstrap 这 样 设计 








@ee Flasky 


© Reade mm 





<a) @ localhost:5000 


Hello, Dave! 


What is your name? 


Submit 


























@ee Flasky ww 


[<I¥||@localhostso00 © Laeaces) [©]» 












Hello, Stranger! 


What is your name? 


This field is required. 








Submit 

















4-3 ”验证 失败 后 显示 的 Web 表单 


4.5 重 定 向 和 用 户 会 话 


最 新 版 的 hello.py 存在 一 个 可 用 性 问题 。 用 户 输入 名 字 后 提交 表单 ， 然 后 点 击 浏览 器 的 刷 
新 按钮 ， 会 看 到 一 个 莫名 其 妙 的 警告 ， 要 求 在 再 次 提交 表单 之 前 进行 确认 。 之 所 以 出 现 这 
种 情况 ， 是 因为 刷新 页 面 时 浏览 器 会 重新 发 送 之 前 已 经 发 送 过 的 最 后 一 个 请 求 。 如 果 这 个 
请 求 是 一 个 包含 表单 数据 的 PosT 请 求 ， 刷 新 页 面 后 会 再 次 提交 表单 。 大 多 数 情况 下 ， 这 并 
不 是 理想 的 处 理 方式 。 







































































很 多 用 户 都 不 理解 浏览 器 发 出 的 这 个 警告 。 基 于 这 个 原因 ， 最 好 别 让 Web 程序 把 PosT 请 
求 作为 浏览 器 发 送 的 最 后 一 个 请 求 。 


这 种 需求 的 实现 方式 是 ， 使 用 重 定向 作为 P05T 请 求 的 响应 ， 而 不 是 使 用 常规 响应 。 重 定 
向 是 一 种 特殊 的 响应 ， 响 应 内 容 是 URL， 而 不 是 包含 HTML 代码 的 字符 串 。 浏 览 器 收 到 
这 种 响应 时 ， 会 向 重 定向 的 URL 发 起 GET 请 求 ， 显 示 页 面 的 内 容 。 这 个 页 面 的 加 载 可 能 
要 多 花 几 微 秒 ， 因 为 要 先 把 第 二 个 请 求 发 给 服务 器 。 除 此 之 外 ， 用 户 不 会 察觉 到 有 什么 不 
同 。 现 在 ， 最 后 一 个 请 求 是 GET 请 求 ， 所 以 刷新 命令 能 像 预 期 的 那样 正常 使 用 了 。 这 个 技 
巧 称 为 Post/ 重 定向 /Get 模式 。 

















但 这 种 方法 会 带 来 另 一 个 问题 。 程 序 处 理 PosT 请 求 时 ， 使 用 form.name.data 获取 用 户 输 
入 的 名 字 ， 可 是 一 旦 这 个 请 求 结束 ， 数 据 也 就 丢失 了 。 因 为 这 个 PosT 请 求 使 用 重 定向 处 
里， 所 以 程序 需要 保存 输入 的 名 字 ， 这 样 重 定向 后 的 请 求 才 能 获得 并 使 用 这 个 名 字 ， 从 而 
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构建 真正 的 响应 。 

程序 可 以 把 数据 存储 在 用 户 会 话 中 ， 在 请 求 之 间 “ 记 住 ” 数 据 。 用 户 会 话 是 一 种 私有 存 
储 ， 存 在 于 每 个 连接 到 服务 器 的 客户 端 中 。 我 们 在 第 2 章 介绍 过 用 户 会 话 ， 它 是 请 求 上 下 
文中 的 变量 ， 名 为 session， 像 标准 的 Python 字典 一 样 操 作 。 

















默认 情况 下 ， 用 户 会 话 保存 在 客户 端 cookie 中 ， 使 用 设置 的 SECRET_KEY 进 
行 加 密 签名 。 如 果 自 改 了 cookie 中 的 内 容 ， 签 名 就 会 失效 ， 会 话 也 会 随 之 











示例 4-5 是 index() 视图 函数 的 新 版 本 ， 实 现 了 重 定向 和 用 户 会 话 。 











示例 4-5 _ hello.py: 重 定向 和 用 户 会 话 
from flask import Flask, render_template, session, redirect, url_for 
@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate_on_submit(): 
session['name'] = form.name.data 


return redirect(url_for('index')) 
return render_template('index.html', form=form, name=session.get('name')) 


在 程序 的 前 一 个 版 本 中 ， 局 部 变量 name 被 用 于 存储 用 户 在 表单 中 输入 的 名 字 。 这 个 变量 现 
在 保存 在 用 户 会 话 中 ， 即 session[ 'name'] ， 所 以 在 两 次 请 求 之 间 也 能 记 住 输入 的 值 。 


现在 ， 包 含 合 法 表单 数据 的 请 求 最 后 会 调用 redirect() 函数 。redirect() 是 个 辅助 函数 ， 
用 来 生成 HTTP 重 定向 响应 。redirect() 国 数 的 参数 是 重 定向 的 URL， 这 里 使 用 的 重 定向 
URL 是 程序 的 根 地 址 ， 因 此 重 定向 响应 本 可 以 写 得 更 简单 一 些 ， 写 成 redirect('/'), 但 
却 会 使 用 Flask 提供 的 URL 生成 函数 url_for()。 推 荐 使 用 url_for() 生成 URL， 因 为 这 
个 函数 使 用 URL 映射 生成 URL， 从 而 保证 URL 和 定义 的 路 由 兼容 ， 而 且 修 改 路 由 名 字 后 
依然 可 用 。 


url_for() 国 数 的 第 一 个 且 唯一 必须 指定 的 参数 是 端点 名 ， 即 路 由 的 内 部 名 字 。 默 认 情 
况 下 ， 路 由 的 端点 是 相应 视图 函数 的 名 字 。 在 这 个 示例 中 ， 处 理 根 地 址 的 视图 函数 是 
index()， 因 此 传 给 url_for() 函数 的 名 字 是 index。 









































最 后 一 处 改动 位 于 render_function() 函数 中 ,使 用 session.get('name') 直接 从 会 话 中 读 
取 name 参数 的 值 。 和 普通 的 字典 一 样 ， 这 里 使 用 get() 获取 字典 中 键 对 应 的 值 以 避免 未 找 
到 键 的 异常 情况 ， 因 为 对 于 不 存在 的 键 ，get() 会 返回 默认 值 None。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 可 以 执行 qit checkout 4b 
签 出 程序 的 这 个 版 本 。 











使 用 这 个 版 本 的 程序 时 ， 刷 新 浏览 器 页 面 ， 你 看 到 的 新 页 面 就 和 预期 一 样 了 。 











4.6” ”Flash 消息 


请 求 完成 后 ， 有 时 需要 让 用 户 知道 状态 发 生 了 变化 。 这 里 可 以 使 用 确认 消息 、 警 告 或 者 错 
误 提 醒 。 一 个 典型 例子 是 ， 用 户 提 交 了 有 一 项 错误 的 登录 表单 后 ， 服 务 器 发 回 的 响应 重新 
渲染 了 登录 表单 ， 并 在 表单 上 面 显示 一 个 消息 ， 提 示 用 户 用 户 名 或 密码 错误 。 




















这 种 功能 是 Flask 的 核心 特性 。 如 示例 4-6 所 示 ，flash() 函数 可 实现 这 种 效果 。 


示例 4-6 ”hello.py: Flash 消息 


from flask import Flask, render_template, session, redirect, url_for, flash 


@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate_on_submit(): 
old_name = session.get('name') 
if old_name is not None and old_name != form.name.data: 
flash('Looks like you have changed your name!') 
session['name'] = form.name.data 
return redirect(url_for('index')) 
return render_template('index.html', 
form = form, name = session.get('name')) 


在 这 个 示例 中 ， 每 次 提交 的 名 字 都 会 和 存储 在 用 户 会 话 中 的 名 字 进 行 比较 ， 而 会 话 中 存储 
的 名 字 是 前 一 次 在 这 个 表单 中 提交 的 数据 。 如 果 两 个 名 字 不 一 样 ， 就 会 调用 flash() 函数 ， 
在 发 给 客户 端的 下 一 个 响应 中 显示 一 个 消息 。 

仅 调用 flash() 函数 并 不 能 把 消息 显示 出 来 ， 程 序 使 用 的 模板 要 泻 染 这 些 消息 。 最 好 在 
基 模 板 中 泻 染 Flash 消息 ， 因 为 这 样 所 有 页 面 都 能 使 用 这 些 消息 。Flask 把 get_flashed_ 
messages() 旷 数 开放 给 模板 ， 用 来 获取 并 泻 染 消息 ， 如 示例 4-7 所 示 。 




















示例 4-7 ”templates/base.html: 演 染 Flash 消息 


{% block content %} 
<div class="container"> 
{% for message in get flashed messages() %} 
<div class="alert alert-warning"> 
<button type="button" class="close" data-dismiss="alert">&times;</button> 
{{ message }} 
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</div> 
{% endfor %} 


{% block page_content %}{% endblock %} 
</div> 
{% endblock %} 





在 这 个 示例 中 ， 使 用 Bootstrap 提供 的 警报 CSS 样式 演 染 警告 消息 (如 图 4-4 所 示 )。 

















eee Flasky ww 








[< || 人 || @ localhost:s000/ ndex c liReaden) [QS 





Looks like you have changed your namel 


Hello, Susan! 


What is your name? 


Submit 


于 mm 




















4-4 ”Flash 消息 


在 模板 中 使 用 循环 是 因为 在 之 前 的 请 求 循环 中 每 次 调用 flash() 函数 时 都 会 生成 一 个 消息 ， 
所 以 可 能 有 多 个 消息 在 排队 等 待 显 示 。get_flashed_messages() 函数 获取 的 消息 在 下 次 调 
用 时 不 会 再 次 返回 ， 因 此 Flash 消息 只 显示 一 次 ， 然 后 就 消失 了 。 











如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
4c 签 出 程序 的 这 个 版 本 。 














从 Web 表单 中 获取 用 户 输入 的 数据 是 大 多 数 程序 都 需要 的 功能 ， 把 数据 保存 在 永久 存储 器 
中 也 是 一 样 。 下 一 章 将 介绍 如 何在 Flask 中 使 用 数据 库 。 








第 5 章 


数据 库 





数据 库 按照 一 定 规则 保存 程序 数据 ， 程 序 再 发 起 查询 取 回 所 需 的 数据 。 A 
于 关系 模型 的 数据 库 ， 这 种 数据 库 也 称 为 SQL 数据 库 ， 因 为 它们 使 用 结构 化 查询 语言 。 

过 最 近 几 年 文档 数据 库 和 键 值 对 数据 库 成 了 流行 人 
数据 库 。 


5.1 SQL 数据 库 


关系 型 数据 库 把 数据 存储 在 表 中 ， 表 模拟 程序 中 不 同 的 实体 。 例 如 ， 订 单 管理 程序 的 数据 
库 中 可 能 有 表 customers、products 和 orders。 


表 的 列 数 是 固定 的 ， 行 数 是 可 变 的 。 列 定义 表 所 表示 的 实体 的 数据 属性 。 例 如 ，customers 
表 中 可 能 有 name、address、phone 等 列 。 表 中 的 行 定义 各 列 对 应 的 真实 数据 。 


表 中 有 个 特殊 的 列 ， 称 为 主键 ， 其 值 为 表 中 各 行 的 唯一 标识 符 。 表 中 还 可 以 有 称 为 外 键 的 
列 ， 引 用 同一 个 表 或 不 同 表 中 某 行 的 主键 。 行 之 间 的 这 种 联系 称 为 关系 ， 这 是 关系 型 数据 
库 模型 的 基础 。 














图 5-1 展示 了 一 个 简单 数据 库 的 关系 图 。 这 个 数据 库 中 有 两 个 表 ， 分 别 存储 用 户 和 用 户 角 
色 。 连 接 两 个 表 的 线 代表 两 个 表 之 间 的 关系 。 
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id 


Username 
password 
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图 5-1 关系 型 数据 库 示例 


在 这 个 数据 库 关系 图 中 ，roles 表 存 储 所 有 可 用 的 用 户 角色 ， 每 个 角色 都 使 用 一 个 唯一 的 
id 值 ( 即 表 的 主键 ) 进行 标识 。users 表 包 含 用 户 列表 ， 每 个 用 户 也 有 唯一 的 id 值 。 除 了 
id 主键 之 外 ，roles 表 中 还 有 name 列 ，users 表 中 还 有 username 列 和 password 列 。users 
表 中 的 role_id 列 是 外 键 ， 引 用 角色 的 id， 通 过 这 种 方式 为 每 个 用 户 指定 角色 。 


从 这 个 例子 可 以 看 出 ， 关 系 型 数据 库存 储 数据 很 高 效 ， 而 且 避 免 了 重复 。 将 这 个 数据 库 中 
的 用 户 角色 重 命 名 也 很 简单 ， 因 为 角色 名 只 出 现在 一 个 地 方 。 一 旦 在 roles 表 中 修改 完 角 
色 名 ， 所 有 通过 role_id 引用 这 个 角色 的 用 户 都 能 立即 看 到 更 新 。 


但 从 另 一 方面 来 看 ， 把 数据 分 别 存放 在 多 个 表 中 还 是 很 复杂 的 。 生 成 一 个 包含 角色 的 用 户 
列表 会 遇 到 一 个 小 问题 ， 因 为 在 此 之 前 要 分 别 从 两 个 表 中 读 取 用 户 和 用 户 角色 ， 再 将 其 联 
结 起 来 。 关 系 型 数据 库 引 擎 为 联结 操作 提供 了 必要 的 支持 。 


5.2 NoSQL 数 据 库 


所 有 不 遵循 上 方 所 述 的 关系 模型 的 数据 库 统称 为 NoSQL 数据 库 。NoSQL 数据 库 一 般 使 用 
集合 代替 表 ， 使 用 文档 代替 记录 。NoSQL 数据 库 采用 的 设计 方式 使 联结 变 得 困难 ， 所 以 大 
多 数 数据 库 根 本 不 支持 这 种 操作 。 对 于 结构 如 图 5-1 所 示 的 NoSQL 数据 库 ， 若 要 列 出 各 
用 户 及 甚 角色， 就 需要 在 程序 中 执行 联结 操作 ， 即 先 读 取 每 个 用 户 的 rote_id， 再 在 roles 
表 中 搜索 对 应 的 记录 。 


NoSQL 数据 库 更 适合 设计 成 如 图 5-2 所 示 的 结构 。 这 是 执行 反 规范 化 操作 得 到 的 结果 ， 它 
减少 了 表 的 数量 ， 却 增加 了 数据 重复 量 。 
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图 5-2 ”NoSQL 数据 库 示例 








这 种 结构 的 数据 库 要 把 角色 名 存储 在 每 个 用 户 中 。 如 此 一 来 ， 将 角色 重 命名 的 操作 就 变 得 
很 耗 时 ， 可 能 需要 更 新 大 量 文档 。 


使 用 NoSQL 数据 库 当 然 也 有 好 处 。 数 据 重复 可 以 提升 查询 速度 。 列 出 用 户 及 其 角色 的 操 
作 很 简单 ， 因 为 无 需 联结 。 

5.3 ”使 用 SQL 还 是 NoSQL 

SQL 数据 库 擅 于 用 高 效 且 紧凑 的 形式 存储 结构 化 数据 。 这 种 数据 库 需 要 花费 大 量 精力 保证 
数据 的 一 致 性 。NoSQL 数据 库 放 宽 了 对 这 种 一 致 性 的 要 求 ， 从 而 获得 性 能 上 的 优势 。 

对 不 同类 型 数据 库 的 全 面 分 析 、 对 比 超出 了 本 书 范 畴 。 对 中 小 型 程序 来 说 ，SQL 和 NoSQL 
数据 库 都 是 很 好 的 选择 ， 而 且 性 能 相当 。 


5.4 ”Python 数据 库 框 架 


大 多 数 的 数据 库 引 擎 都 有 对 应 的 Python 包 ， 包 括 开源 包 和 商业 包 。Flask 并 不 限制 你 使 
用 何 种 类 型 的 数据 库 包 ， 因 此 可 以 根据 自己 的 喜好 选择 使 用 MySQL、Postgres、SQLite、 
Redis、MongoDB 或 者 CouchDB。 









































如 果 这 些 都 无 法 满足 需求 ， 还 有 一 些 数据 库 抽 象 层 代码 包 供 选择 ， 例 如 SQLAlchemy 和 
MongoEngine。 你 可 以 使 用 这 些 抽 象 包 直接 处 理 高 等 级 的 Python 对 象 ， 而 不 用 处 理 如 表 、 
文档 或 查询 语言 此 类 的 数据 库 实 体 。 
选择 数据 库 框架 时 ， 你 要 考虑 很 多 因素 。 

易 用 性 

如 果 直 接 比 较 数 据 库 引 擎 和 数据 库 抽 象 层 ， 显 然后 者 取胜 。 抽 象 层 ， 也 称 为 对 象 关 系 


映射 (ObjectrRelational Mapper，ORM) 或 对 象 文 档 映 射 (ObjectDocument Mapper， 
ODM)， 在 用 户 不 知觉 的 情况 下 把 高 层 的 面向 对 象 操 作 转 换 成 低层 的 数据 库 指令 。 





























性 能 
ORM 和 ODM 把 对 象 业务 转换 成 数据 库 业务 会 有 一 定 的 损耗 。 大 多 数 情况 下 ， 这 种 性 
能 的 降低 微不足道 ， 但 也 不 一 定 都 是 如 此 。 一 般 情 况 下 ，ORM 和 ODM 对 生产 率 的 提 
升 远 远 超过 了 这 一 丁点 儿 的 性 能 降低 ， 所 以 性 能 降低 这 个 理由 不 足以 说 服用 户 完全 放弃 
ORM 和 ODM。 真 正 的 关键 点 在 于 如 何人 选择 一 个 能 直接 操作 低层 数据 库 的 抽象 屋 ， 以 
防 特定 的 操作 需要 直接 使 用 数据 库 原生 指令 优化 。 

















可 移植 性 
选择 数据 库 时 ， 必 须 考 虑 其 是 否 能 在 你 的 开发 平台 和 生产 平台 中 使 用 。 例 如 ， 如 果 你 打 
算 利 用 云 平台 托管 程序 ， 就 要 知道 这 个 云 服 务 提供 了 哪些 数据 库 可 供 选 择 。 
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可 移植 性 还 针对 ORM 和 ODM。 尽 管 有 些 框架 只 为 一 种 数据 库 引 擎 提供 抽象 层 ， 但 其 
他 框架 可 能 做 了 更 高 层 的 抽象 ， 它 们 支持 不 同 的 数据 库 引 擎 ， 而 且 都 使 用 相同 的 面向 对 
象 接 口 。SQLAlchemy ORM 就 是 一 个 很 好 的 例子 ， 它 支持 很 多 关系 型 数据 库 引 擎 ， 包 
括 流 行 的 MySQL、Postgres 和 SQLite。 





FLask 集 成 度 

选择 框架 时 ， 你 不 一 定 非得 选择 已 经 集成 了 Flask 的 框架 ， 但 选择 这 些 框架 可 以 节省 
你 编写 集成 代码 的 时 间 。 使 用 集成 了 Flask 的 框架 可 以 简化 配置 和 操作 ， 所 以 专门 为 
Flask 开发 的 扩展 是 你 的 首选 。 

















基于 以 上 因素 ， 本 书 选 择 使 用 的 数据 库 框 架 是 Flask-SQLAlchemy (http://pythonhosted.org/ 
Flask-SQLAIlchemy/) ， 这 个 Flask 扩展 包装 了 SQLAlchemy (http:/www.sqlalchemy.org/) 框架 。 


5.5 ”使 用 Flask-SQLAIchemy 管 理 数 据 库 


Flask-SQLAlchemy 是 一 个 Flask 扩展 ， 简 化 了 在 Flask 程序 中 使 用 SQLAlchemy 的 操作 。 
SQLAlchemy 是 一 个 很 强大 的 关系 型 数据 库 框 架 ， 支持 多 种 数据 库 后 台 。SQLAIlchemy 提 
供 了 高 层 ORM， 也 提供 了 使 用 数据 库 原生 SQL 的 低层 功能 。 











和 其 他 大 多 数 扩展 一 样 ，Flask-SQLAlchemy 也 使 用 pip 安装 : 
(venv) $ pip install flask-sqlalchemy 


在 Flask-SQLAlchemy 中 ， 数 据 库 使 用 URL 指定 。 最 流行 的 数据 库 引 敬 采 用 的 数据 库 URL 
格式 如 表 5-1 所 示 。 





表 5-1 FLask-SQLAIchemy 数 据 库 URL 





数据 库 引擎 URL 

MySQL mysgql:/username:password@hostname/database 
Postgres postgresql://lusername:password@hostname/database 
SQLite (Unix) sqlite:////absolute/path/to/database 

SQLite (Windows) sqlite:///c:/absolute/path/to/database 


在 这 些 URL 中 ，hostname 表示 MySQL 服务 所 在 的 主机 ， 可 以 是 本 地 主机 (localhos?)， 
也 可 以 是 远程 服务 器 。 数 据 库 服务 器 上 可 以 托管 多 个 数据 库 ， 因 此 database 表示 要 使 用 的 
数据 库 名 。 如 果 数 据 库 需要 进行 认证 ，username 和 password 表示 数据 库 用 户 密令 。 








SQLite 数据 库 不 需要 使 用 服务 器 ， 因 此 不 用 指定 hostname、username 和 
password。URL 中 的 database 是 硬盘 上 文件 的 文件 名 。 








程序 使 用 的 数据 库 URL 必须 保存 到 Flask 配置 对 象 的 SQLALCHEMY_DATABASE_URI 键 中 。 配 
置 对 象 中 还 有 一 个 很 有 用 的 选项 ， 即 SQLALCHEMY_COMMIT_ON_TEARDOWN 键 ， 将 其 设 为 True 
时 ， 每 次 请 求 结束 后 都 会 自动 提交 数据 库 中 的 变动 。 其 他 配置 选项 的 作用 请 参阅 Flask- 
SQLAlchemy 的 文档 。 示 例 5-1 展示 了 如 何 初始 化 及 配置 一 个 简单 的 SQLite 数据 库 。 





示例 5-1 hello.py: 配置 数据 库 
from fLask.ext.sqLaLchemy import SQLALchemy 





basedir = os.path.abspath(os.path.dirname(__file )) 


app = Flask(__name_ ) 
app.config['SQLALCHEMY_DATABASE_URI'] =\ 

'sqlite:///' + os.path.join(basedir, 'data.sqlite') 
app.config['SQLALCHEMY_COMMIT_ON_TEARDOWN'] = True 


db = SQLALchemy(app) 


db 对 象 是 SQLALchemy 类 的 实例 ， 表 示 程 序 使 用 的 数据 库 ， 同 时 还 获得 了 Flask-SQLAlchemy 
提供 的 所 有 功能 。 


5.6 定义 模型 


模型 这 个 术语 表示 程序 使 用 的 持久 化 实体 。 在 ORM 中 ， 模 型 一 般 是 一 个 Python 类 ， 类 中 
的 属性 对 应 数据 库 表 中 的 列 。 


Flask-SQLAlchemy 创建 的 数据 库 实例 为 模型 提供 了 一 个 基 类 以 及 一 系列 辅助 类 和 辅助 函 
数 ， 可 用 于 定义 模型 的 结构 。 图 5-1 中 的 roles 表 和 users 表 可 定义 为 模型 Role 和 User， 
如 示例 5-2 所 示 。 






































示例 5-2 hello.py: 定义 Role 和 User 模型 


class Role(db.Model): 
_ tabLename_ = 'roles' 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String(64), unique=True) 


def __repr__(self): 
return '<Role %r>' % seLf.name 


class User(db.Model): 
__tablename _ = 'Users' 
tid = db.Column(db.Integer, primary_key=True) 
username = db.Column(db.String(64), unique=True, index=True) 


def __repr__(self): 
return '<User %r>' % seLf.username 


类 变量 _tablename__ 定义 在 数据 库 中 使 用 的 表 名 。 如 果 没 有 定义 _tablename__，Flask- 
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SQLAIchemy 会 使 用 一 个 默认 名 字 ， 但 默认 的 表 名 没有 遵守 使 用 复数 形式 进行 命名 的 约定 ， 
所 以 最 好 由 我 们 自己 来 指定 表 名 。 其 余 的 类 变量 都 是 该 模型 的 属性 ， 被 定义 为 db.Column 


类 的 实例 。 





db.Column 类 构造 函数 的 第 一 个 参数 是 数据 库 列 和 模型 属性 的 类 型 。 表 5-2 列 出 了 一 些 可 用 
的 列 类 型 以 及 在 模型 中 使 用 的 Python 类 型 。 








表 5-2 ”最 常用 的 SQLAIchemy 列 类 型 

















类 型 名 Python 类 型 说 明 

Integer int 普通 整数 ， 一 般 是 32 位 

SmallInteger int 取 值 范围 小 的 整数 ， 一 般 是 16 位 

BigInteger 。 ”int 或 long 不 限制 精度 的 整数 

Float float 浮 点 数 

Numeric decimal.Decimal 定点 数 

String str 变 长 字符 串 

Text str 变 长 字符 串 ， 对 较 长 或 不 限 长 诬 的 字符 串 做 了 优化 
Unicode unicode 变 长 Unicode 字符 串 

UnicodeText unicode 变 长 Unicode 字符 串 ， 对 较 长 或 不 限 长 度 的 字符 串 做 了 优化 
Boolean bool 布尔 值 

Date datetime.date 日 期 

Time datetime. time 时 间 

DateTime datetime.datetime 日 期 和 时 间 

Interval datetime. timedelta 时 间 间 隔 

Enum str 一 组 字符 串 

PickleType 。 任何 Python 对 象 自动 使 用 Pickle 序列 化 

LargeBinary str 二 进 制 文件 














db.Column 中 其 余 的 参数 指定 属性 的 配置 选项 。 表 5-3 列 出 了 一 些 可 用 选项 。 





表 5-3 ”最 常 使 用 的 SQLAIchemy 列 选项 


选项 名 


说 明 





primary_key 
unique 
index 
nullable 
default 


如 果 设 为 True， 这 列 就 是 表 的 主键 

如 果 设 为 True， 这 列 不 允许 出 现 重 复 的 值 

如 果 设 为 True， 为 这 列 创建 索引 ， 提 升 查询 效率 

如 果 设 为 True， 这 列 允 许 使 用 空 值 ， 如 果 设 为 Fatse， 这 列 不 允许 使 用 空 值 
为 这 列 定义 默认 值 




















Flask-SQLAlchemy 要 求 每 个 模型 都 要 定义 主键 ， 这 一 列 经 常 命名 为 id。 





虽然 没有 强制 要 求 ， 但 这 两 个 模型 都 定义 了 repr() 方法 ， 返 回 一 个 具有 可 读 性 的 字符 
串 表示 模型 ， 可 在 调试 和 测试 时 使 用 。 


5.7 关系 


关系 型 数据 库 使 用 关系 把 不 同 表 中 的 行 联系 起 来 。 图 5-1 所 示 的 关系 图 表示 用 户 和 角色 之 
间 的 一 种 简单 关系 。 这 是 角色 到 用 户 的 一 对 多 关系 ， 因 为 一 个 角色 可 属于 多 个 用 户 ， 而 每 
个 用 户 都 只 能 有 一 个 角色 。 



































5-1 中 的 一 对 多 关系 在 模型 类 中 的 表示 方法 如 示例 5-3 所 示 。 


示例 5-3 hello.py: 关系 
class Role(db.Model): 
# ... 
users = db.relationship('User', backref='role') 


class User(db.Model): 
# ... 
role_id = db.Column(db.Integer, db.ForeignKey('roles.id')) 








如 图 5-1 所 示 ， 关 系 使 用 users 表 中 的 外 键 连接 了 两 行 。 添 加 到 User 模型 中 的 role_id 列 
被 定义 为 外 键 ， 就 是 这 个 外 键 建 立 起 了 关系 。 传 给 b.ForeignKey() 的 参数 'roles.id' 表 
明 ， 这 列 的 值 是 roles 表 中 行 的 id 值 。 

















添加 到 Rote 模型 中 的 users 属性 代表 这 个 关系 的 面向 对 象 视 角 。 对 于 一 个 Role 类 的 实例 ， 
其 users 属性 将 返回 与 角色 相关 联 的 用 户 组 成 的 列表 。db.retLationship() 的 第 一 个 参数 表 
明 这 个 关系 的 另 一 端 是 哪个 模型 。 如 果 模 型 类 尚未 定义 ， 可 使 用 字符 串 形式 指定 。 








db.relationship() 中 的 backref 参数 向 User 模型 中 添加 一 个 role 属性 ， 从 而 定义 反问 关 
系 。 这 一 属性 可 替代 role_id 访问 Role 模型 ， 此 时 获取 的 是 模型 对 象 ， 而 不 是 外 键 的 值 。 





大 多 数 情况 下 ，db.relationship() 都 能 自行 找到 关系 中 的 外 键 ， 但 有 时 却 无 法 决定 把 
哪 一 列 作为 外 键 。 例 如 ， 如 果 User 模型 中 有 两 个 或 以 上 的 列 定义 为 Role 模型 的 外 键 ， 
SQLAlchemy 就 不 知道 该 使 用 哪 列 。 如 果 无 法 决定 外 键 ， 你 就 要 为 db.relationship() 提供 
额外 参数 ， 从 而 确定 所 用 外 键 。 表 5-4 列 出 了 定义 关系 时 常用 的 配置 选项 。 
































表 5-4 ”常用 的 SQLAIchemy 关 系 选 项 


























选项 名 说 明 

backref 在 关系 的 另 一 个 模型 中 添加 反 向 引用 

primaryjoin 明确 指定 两 个 模型 之 间 使 用 的 联结 条 件 。 只 在 模棱两可 的 关系 中 需要 指定 

lazy 指定 如 何 加 载 相 关 记 录 。 可 选 值 有 select (首次 访问 时 按 需 加 载 )、inmediate ( 源 对 象 加 
载 后 就 加 载 )、joined (加 载 记录 ， 但 使 用 联结 )、subquery (立即 加 载 ， 但 使 用 子 查 询 )， 














noload ( 永 不 加 载 ) 和 dynamic (不 加 载 记录 ， 但 提供 加 载 记录 的 查询 ) 
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选项 名 说 明 

uselist 如 果 设 为 Fales， 不 使 用 列表 ， 而 使 用 标量 值 
order_by 指定 关系 中 记录 的 排序 方式 

secondary 指定 多 对 多 关系 中 关系 表 的 名 字 
secondaryjoin ”SQLAlchemy 无 法 自行 决定 时 ， 指 定 多 对 多 关系 中 的 二 级 联结 条 件 

















如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5a 签 出 程序 的 这 个 版 本 。 























除了 一 对 多 之 外 ， 还 有 几 种 其 他 的 关系 类 型 。 一 对 一 关系 可 以 用 前 面 介 绍 的 一 对 多 关系 
表示 ， 但 调用 db.relationship() 时 要 把 useList 设 为 False, 把 “多 ” 变 成 “一 ”。 多 对 
一 关系 也 可 使 用 一 对 多 表示 ， 对 调 两 个 表 即 可 ， 或 者 把 外 键 和 db.relationship() 都 放 在 
“多 ”这 一 侧 。 最 复杂 的 关系 类 型 是 多 对 多 ， 需 要 用 到 第 三 张 表 ， 这 个 表 称 为 关系 表 。 你 
将 在 第 12 章 学 习 多 对 多 关系 。 


5.8 数据 库 操作 
现在 模型 已 经 按照 图 5-1 所 示 的 数据 库 关系 图 完成 配置 ， 可 以 随时 使 用 了 。 学 习 如 何 使 用 
模型 的 最 好 方法 是 在 Python shell 中 实际 操作 。 接 下 来 的 儿 节 将 介绍 最 常用 的 数据 库 操作 。 

















5.8.1 创建 表 


首先 ， 我 们 要 让 Flask-SQLAlchemy 根据 模型 类 创建 数据 库 。 方 法 是 使 用 db.create_all() 
函数 : 
(venv) $ python hello.py shell 


>>> from hello import db 
>>> db.create all() 





如 果 你 查看 程序 目录 ， 会 发 现 新 建 了 一 个 名 为 data.sqlite 的 文件 。 这 个 SQLite 数据 库 文 件 
的 名 字 就 是 在 配置 中 指定 的 。 如 果 数 据 库 表 已 经 存在 于 数据 库 中 ， 那 么 db.create_all() 
不 会 重新 创建 或 者 更 新 这 个 表 。 如 果 修 改 模型 后 要 把 改动 应 用 到 现 有 的 数据 库 中 ， 这 一 特 
性 会 带 来 不 便 。 更 新 现 有 数据 库 表 的 粗暴 方式 是 先 删除 旧 表 再 重新 创建 : 





























>>> db.drop_all() 
>>> db.create_alLL() 





遗憾 的 是 ， 这 个 方法 有 个 我 们 不 想 看 到 的 副作用 ， 它 把 数据 库 中 原 有 的 数据 都 销毁 了 。 本 
章 末 尾 将 会 介绍 一 种 更 好 的 方式 用 于 更 新 数据 库 。 





5.8.2 插入 行 
下 面 这 段 代码 创建 了 一 些 角色 和 用 户 : 





>>> from hello import Role, User 

>>> admin_role = Role(name='Admin') 

>>> mod_role = Role(name='Moderator') 

>>> User_role = Role(name='User') 

>>> User_john = User(username='john', role=admin_role) 
>>> User_susan = User(username='suysan', role=user_role) 
>>> User_david = User(username='david', role=user_role) 





模型 的 构造 函数 接受 的 参数 是 使 用 关键 字 参 数 指定 的 模型 属性 初始 值 。 注 意 ，role 属性 也 
可 使 用 ， 虽然 它 不 是 真正 的 数据 库 列 ， 但 却 是 一 对 多 关系 的 高 级 表示 。 这 些 新 建 对 象 的 id 
属性 并 没有 明确 设 定 ， 因 为 主键 是 由 Flask-SQLAlchemy 管理 的 。 现 在 这 些 对 象 只 存在 于 
Python 中 ， 还 未 写 入 数据 库 。 因 此 id 尚未 赋值 : 


























>>> print(admin_role.id) 


None 
>>> print(mod_role.id) 
None 
>>> print(user_role.id) 
None 

















通过 数据 库 会 话 管 理 对 数据 库 所 做 的 改动 ， 在 Flask-SQLAlchemy 中 ， 会 话 由 db.session 
表示 。 准 备 把 对 象 写 入 数据 库 之 前 ， 先 要 将 其 添加 到 会 话 中 : 




















>>> db.session.add(admin_role) 
>>> db.session.add(mod_role) 
>>> db.session.add(user_role) 
>>> db.session.add(user_john) 
>>> db.session.add(user_susan) 
>>> db.session.add(user_david) 


或 者 简写 成 : 


>>> db.session.add all([admin_role, mod_role, user_role, 
user_john, user_susan, user_david]) 


为 了 把 对 象 写 人 数据库， 我 们 要 调用 commit() 方法 提交 会 话 : 





>>> db.session.commit() 


再 次 查看 id 属性 ， 现 在 它们 已 经 赋值 了 : 
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>>> print(admin_role.id) 
1 

>>> print(mod_role.id) 

2 

>>> print(user_role.id) 
3 


数据 库 会 话 db.session 和 第 4 章 介绍 的 Flasksession 对 象 没有 关系 。 数 据 库 
会 话 也 称 为 事务 。 


数据 库 会 话 能 保证 数据 库 的 一 臻 性。 提交 操作 使 用 原子 方式 把 会 话 中 的 对 象 全 部 写 入 数据 
库 。 如 果 在 写 入 会 话 的 过 程 中 发 生 了 错误 ， 整 个 会 话 都 会 失效 。 如 果 你 始终 把 相关 改动 放 
在 会 话 中 提交 ， 就 能 避免 因 部 分 更 新 导致 的 数据 库 不 一 致 性 。 





数据 库 会 话 也 可 回 滚 。 调 用 db.session.rollback() 后 ， 添 加 到 数据 库 会 话 
中 的 所 有 对 象 都 会 还 原 到 它们 在 数据 库 时 的 状态 。 


5.8.3 ”修改 行 
在 数据 库 会 话 上 调用 add() 方法 也 能 更 新 模型 。 我 们 继续 在 之 前 的 shell 会 话 中 进行 操作 ， 
下 面 这 个 例子 把 "Admin" 角色 重 命名 为 "Administrator": 

>>> admin_role.name = 'Administrator’' 


>>> db.session.add(admin_role) 
>>> db.session.commit() 


5.8.4 删除 行 
数据 库 会 话 还 有 个 delete() 方法 。 下 面 这 个 例子 把 "Moderator" 角色 从 数据 库 中 删除 : 


>>> db.session.delete(mod_role) 
>>> db.session.commit() 


注意 ， 删 除 与 插入 和 更 新 一 样 ， 提 交 数 据 库 会 话 后 才 会 执行 。 








5.8.5 查询 行 
Flask-SQLAlchemy 为 每 个 模型 类 都 提供 了 query 对 象 。 最 基本 的 模型 查询 是 取 回 对 应 表 中 
的 所 有 记录 : 
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>>> Role.query.all() 

[<Role u'Administrator'>, <Role u'User'>] 

>>> User .query.all() 

[<User u'john'>, <User U'susan'>，<User u'david'>] 














使 用 过 滤器 可 以 配置 query 对 象 进行 更 精确 的 数据 库 查 询 。 下 面 这 个 例子 查找 角色 为 
"User" 的 所 有 用 户 : 


>>> User .query.filter_by(role=user_role).all() 
[<User u'susan'>, <User u'david'>] 





若 要 查看 SQLAlchemy 为 查询 生成 的 原生 SQL 查询 语句 ， 只 需 把 query 对 象 转换 成 字 
符 串 : 
>>> str(User.query.filter_by(role=user_role)) 


"SELECT Users.id AS Users_id，users.Username AS Users_Username， 
Users.role id AS users_role id FROM users WHERE :param 1 = Users.roLe_id' 


如 果 你 退出 了 shell 会 话 ， 前 面 这 些 例 子 中 创建 的 对 象 就 不 会 以 Python 对 象 的 形式 存在 ， 而 
是 作为 各 自 数据 库 表 中 的 行 。 如 有 果 你 打开 了 一 个 新 的 shell 会 话 ， 就 要 从 数据 库 中 读 取 行 ， 
再 重新 创建 Python 对 象 。 下 面 这 个 例子 发 起 了 一 个 查询 ， 加 载 名 为 "User" 的 用 户 角色 : 


>>> user_role = Role.query.filter_by(name='User').first() 


filter_by() 等 过 滤器 在 query 对 象 上 调用 ， 返 回 一 个 更 精确 的 query 对 象 。 多 个 过 滤器 可 
以 一 起 调用 ， 直 到 获得 所 需 结 果 。 

















表 5-5 列 出 了 可 在 query 对 象 上 调用 的 常用 过 滤器 。 完 整 的 列表 参见 SQLAlchemy 文档 
( http://docs.sqlalchemy.org 站 


表 5-5 ”常用 的 SQLAIchemy 查 询 过 滤器 



































过 滤器 说 明 

filter() 把 过 滤器 添加 到 原 查 询 上 ， 返 回 一 个 新 查询 

filter_by() 把 等 值 过 滤器 添加 到 原 查 询 上 ， 返 回 一 个 新 查询 

limit() 使 用 指定 的 值 限制 原 查询 返回 的 结果 数量 ， 返 回 一 个 新 查询 
offset() 偏 移 原 查询 返回 的 结果 ， 返 回 一 个 新 查询 

order_by() 根据 指定 条 件 对 原 查 询 结果 进行 排序 ， 返 回 一 个 新 查询 
group_by() 根据 指定 条 件 对 原 查 询 结果 进行 分 组 ， 返 回 一 个 新 查询 








在 查询 上 应 用 指定 的 过 着 器 后 ， 通 过 调用 aLL() 执行 查询 ， 以 列表 的 形式 返回 结果 。 除 了 
all() 之 外 ， 还 有 其 他 方法 能 触发 查询 执行 。 表 5-6 列 出 了 执行 查询 的 其 他 方法 。 
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表 5-6 最 常 使 用 的 SQLAIchemy 查 询 执行 函数 










































































苛 沁 说 明 

all() 以 列表 形式 返回 查询 的 所 有 结果 

first() 返回 查询 的 第 一 个 结果 ， 如 果 没 有 结果 ， 则 返回 None 

first_or_404() 返回 查询 的 第 一 个 结果 ， 如 果 没 有 结果 ， 则 终止 请 求 ， 返 回 404 错误 响应 

get() 返回 指定 主键 对 应 的 行 ， 如 果 没 有 对 应 的 行 ， 则 返回 None 

get_or_464() ”返回 指定 主键 对 应 的 行 ， 如 果 没 找到 指定 的 主键 ， 则 终止 请 求 ， 返 回 404 错误 响应 
count() 返回 查询 结果 的 数量 

paginate() 返回 一 个 Paginate 对 象 ， 它 包含 指定 范围 内 的 结果 
关系 和 查询 的 处 理 方式 类 似 。 下 面 这 个 例子 分 别 从 关系 的 两 端 查询 角色 和 用 户 之 间 的 一 对 





多 关系 : 


>>> Users = User_role.users 

>>> USers 

[<User u'susan'>, <User u'david'>] 
>>> users[0].role 

<Role u'User'> 


这 个 例子 中 的 user_role.users 查询 有 个 小 问题 。 执 行 user_role.users 表达 式 时 ， 隐 含 的 
查询 会 调用 aLL() 返回 一 个 用 户 列表 。query 对 象 是 隐藏 的 ， 因 此 无 法 指定 更 精确 的 查询 
过 滤器 。 就 这 个 特定 示例 而 言 ， 返 回 一 个 按照 字母 顺序 排序 的 用 户 列表 可 能 更 好 。 在 示例 
5-4 中 ， 我 们 修改 了 关系 的 设置 ， 加 入 了 lazy = 'dynamic' 参数 ， 从 而 禁止 自动 执行 查询 。 








示例 5-4 ”hello.py: 动态 关系 
class Role(db.Model): 
.ee 


users = db.relationship('User', backref='role', lazy='dynamic') 
# ... 





这 样 配置 关系 之 后 ，user_role.users 会 返回 一 个 尚未 执行 的 查询 ， 因 此 可 以 在 其 上 添加 过 














>>> user_role.users.order_by(User .username).all() 
[<User u'david'>, <User u'susan'>] 

>>> User_role.users.count() 

2 


5.9 在 视图 函数 中 操作 数据 库 


前 一 节 介 绍 的 数据 库 操 作 可 以 直接 在 视图 函数 中 进行 。 示 例 5-5 展示 了 首页 路 由 的 新 版 本 ， 
已 经 把 用 户 输入 的 名 字 写 入 了 数据 库 。 











邮 


示例 5-5 hello.py: 在 视图 函数 中 操作 数据 库 
@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate_on_submit(): 
user = User.query.filter_by(username=form.name.data).first() 
if user is None: 
User = User(username = form.name.data) 
db.session.add(user) 
session['known'] = False 
else: 
session['known'] = True 
session['name'] = form.name.data 
form.name.data = "" 
return redirect(url_for('index')) 
return render_template('index.html', 
form = form, name = session.get('name'), 
known = session.get('known', False)) 


在 这 个 修改 后 的 版 本 中 ， 提 交 表 单 后 ， 程 序 会 使 用 filter_by() 查询 过 滤器 在 数据 库 中 查 
找 提交 的 名 字 。 变 量 known 被 写 入 用 户 会 话 中 ， 因 此 重 定向 之 后 ， 可 以 把 数据 传 给 模板 ， 
用 来 显示 自 定义 的 欢迎 消息 。 注 意 ， 要 想 让 程序 正常 运行 ， 你 必须 按照 前 面 介绍 的 方法 ， 
在 Python shell 中 创建 数据 库 表 。 


对 应 的 模板 新 版 本 如 示例 5-6 所 示 。 这 个 模板 使 用 known 参数 在 欢迎 消息 中 加 入 了 第 二 行 ， 
从 而 对 已 知 用 户 和 新 用 户 显示 不 同 的 内 容 。 











示例 5-6 templates/index.html 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 


{% block title %}FLasky{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<hi>Hello, {% if name %}{{ name }}{% else %}Stranger{% endif %}!</h1i> 
{% if not known %} 
<p>Pleased to meet you!</p> 
{% else %} 
<p>Happy to see you again!</p> 
{% endif %} 

</div> 

{{ wtf.quick_form(form) }} 

{% endblock %} 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5b 签 出 程序 的 这 个 版 本 。 
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5.10 ”集成 Python shell 


每 次 启动 shell 会 话 都 要 导入 数据 库 实例 和 模型 ， 这 真是 份 枯燥 的 工作 。 为 了 避免 一 直 重 复 
导入 ， 我 们 可 以 做 些 配置 ， 让 Flask-Script 的 shell 命令 自动 导入 特定 的 对 象 。 








若 想 把 对 象 添加 到 导入 列表 中 ， 我 们 要 为 shell 命令 注册 一 个 make_context 回调 函数 ， 如 
示例 5-7 所 示 。 


示例 5-7 hello.py: 为 shell 命令 添加 一 个 上 下 文 
from flask.ext.script import Shell 
def make_shell_context(): 


return dict(app=app, db=db, User=User, Role=Role) 
manager .add_command("shell", Shell(make_context=make_shell_context)) 





make_shell_context() 函数 注册 了 程序 、 数 据 库 实例 以 及 模型 ， 因 此 这 些 对 象 能 直接 导入 shell: 











$ python hello.py shell 

>>> app 

<Flask 'app'> 

>>> db 

<SQLALchemy engine='sqlite:////home/flask/flasky/data.sqlite'> 
>>> User 

<class 'app.User'> 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 qtt checkout 
5c 签 出 程序 的 这 个 版 本 。 














5.11 使 用 Flask-Migrate 实 现 数据 库 迁 移 
在 开发 程序 的 过 程 中 ， 你 会 发 现 有 时 需要 修改 数据 库 模 型 ， 而 且 修 改 之 后 还 需要 更 新 数据 库 。 





仅 当 数据 库 表 不 存在 时 ，Flask-SQLAlchemy 才 会 根据 模型 进行 创建 。 因 此 ， 更 新 表 的 唯一 
方式 就 是 先 删除 旧 表 ， 不 过 这 样 做 会 丢失 数据 库 中 的 所 有 数据 。 














更 新 表 的 更 好 方法 是 使 用 数据 库 迁 移 框架 。 源 码 版 本 控制 工具 可 以 跟踪 源码 文件 的 变化 ， 
类 似 地 ， 数 据 库 迁移 框架 能 跟踪 数据 库 模 式 的 变化 ， 然 后 增 量 式 的 把 变化 应 用 到 数据 库 中 。 








SQLAlchemy 的 主力 开发 人 员 编 写 了 一 个 迁移 框架 ， 称 为 Alembic (https://alembic.readthedocs. 
org/en/latest/index.html)。 除 了 直接 使 用 Alembic 之 外 ，Flask 程序 还 可 使 用 Flask-Migrate 
(http://flask-migrate.readthedocs.org/en/latest/) 扩展 。 这 个 扩展 对 Alembic 做 了 轻 量 级 包装 ， 并 
集成 到 Flask-Script 中 ， 所 有 操作 都 通过 Flask-Script 命令 完成 。 
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5.11.1 创建 迁移 仓库 

首先 ， 我们 要 在 虚拟 环境 中 安装 Flask-Migrate: 
(venv) $ pip install flask-migrate 

这 个 扩展 的 初始 化 方法 如 示例 5-8 所 示 。 


示例 5-8 hello.py: 配置 Flask-Migrate 
from flask.ext.migrate import Migrate, MigrateCommand 


# ... 


migrate = Migrate(app, db) 
manager .add_command('db', MigrateCommand) 











为 了 导出 数据 库 迁 移 命 令 ，Flask-Migrate 提供 了 一 个 MigrateCommand 类 ， 可 附加 到 Flask- 
Script 的 manager 对 象 上 。 在 这 个 例子 中 ，MigrateCommand 类 使 用 db 命令 附加 。 


在 维护 数据 库 迁 移 之 前 ， 要 使 用 init 子 命令 创建 迁移 仓库 : 








(venv) $ python hello.py db init 
Creating directory /home/flask/flasky/migrations...done 
Creating directory /home/flask/flasky/migrations/versions...done 
Generating /home/flask/flasky/migrations/alembic.ini...done 
Generating /home/flask/flasky/migrations/env.py...done 
Generating /home/flask/flasky/migrations/env.pyc...done 
Generating /home/flask/flasky/migrations/README...done 
Generating /home/flask/flasky/migrations/script.py.mako...done 
Please edit configuration/connection/logging settings in 
'/home/flask/flasky/migrations/alembic.ini' before proceeding. 





这 个 命令 会 创建 migrations 文件 夹 ， 所 有 迁移 脚本 都 存放 其 中 。 


数据 库 迁 移 仓库 中 的 文件 要 和 程序 的 其 他 文件 一 起 纳入 版 本 控制 。 





4 








5.11.2 创建 迁移 脚本 

在 Alembic 中 ， 数 据 库 迁 移 用 迁移 脚本 表示 。 脚 本 中 有 两 个 国 数 ， 分 别 是 upgrade() 和 
downgrade()。upgrade() 国 数 把 迁移 中 的 改动 应 用 到 数据 库 中 ，downgrade() 国 数 则 将 改动 
删除 。Alembic 具有 添加 和 删除 改动 的 能 力 ， 因 此 数据 库 可 重 设 到 修改 历史 的 任意 一 点 。 


我 们 可 以 使 用 revision 命令 手动 创建 Alembic 迁移 ， 也 可 使 用 migrate 命令 自动 创建 。 
手动 创建 的 迁移 只 是 一 个 骨架 ，upgrade() 和 downgrade() 函数 都 是 空 的 ， 开 发 者 要 使 用 
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Alembic 提供 的 0perations 对 象 指 令 实现 具体 操作 。 自 动 创 建 的 迁移 会 根据 模型 定义 和 数 
据 库 当 前 状态 之 间 的 差异 生成 upgrade() 和 downgrade() 国 数 的 内 容 。 








自动 创建 的 迁移 不 一 定 总 是 正确 的 ， 有 可 能 会 漏 掉 一 些 细节 。 自 动 生成 迁移 
脚本 后 一 定 要 进行 检查 。 








migrate 子 命令 用 来 自动 创建 迁移 脚本 : 





(venv) $ python hello.py db migrate -m "initial migration" 
INFO [alembic.migration] Context impl SQLiteImpl. 
INFO [alembic.migration] Will assume non-transactional DDL. 
INFO [alembic.autogenerate] Detected added table 'roles' 
INFO [alembic.autogenerate] Detected added table 'users' 
INFO [alembic.autogenerate.compare] Detected added index 
'ix_users_username' on '['username']' 
Generating /home/flask/flasky/migrations/versions/1bc 
594146bb5_initial_migration.py...done 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
5d 签 出 程序 的 这 个 版 本 。 注 意 ， 你 不 用 再 生成 程序 的 迁移 ， 因 为 这 个 仓库 已 
经 包含 了 所 有 的 迁移 脚本 。 





5.11.3 更 新 数据 库 


检查 并 修正 好 迁移 脚本 之 后 ， 我 们 可 以 使 用 db upgrade 命令 把 迁移 应 用 到 数据 库 中 : 


(venv) $ python hello.py db upgrade 

INFO [alembic.migration] Context impl SQLiteImpl. 

INFO [alembic.migration] Will assume non-transactional DDL. 

INFO [alembic.migration] Running upgrade None -> 1bc594146bb5, initial migration 


对 第 一 个 迁移 来 说 ， 其 作用 和 调用 db.create_all() 方 法 一 样 。 但 在 后 续 的 迁移 中 ， 
upgrade 命令 能 把 改动 应 用 到 数据 库 中 ， 且 不 影响 其 中 保存 的 数据 。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 请 删除 数据 库 文件 data. 
sqlite， 然 后 执行 Flask-Migrate 提供 的 upgrade 命令 ， 使 用 这 个 迁移 框架 重新 





数据 库 的 设计 和 使 用 是 很 重要 的 话题 ， 甚 至 有 整 本 的 书 对 其 进行 介绍 。 你 应 该 把 本 章 视 作 
一 个 概览 ， 更 高 级 的 话题 会 在 后 续 各 章 中 讨论 。 下 一 章 将 重点 介绍 电子 邮件 的 发 送 。 
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电子 邮件 


很 多 类 型 的 应 用 程序 都 需要 在 特定 事件 发 生 时 提醒 用 户 ， 而 常用 的 通信 方法 是 电子 邮件 。 
虽然 Python 标准 库 中 的 smtplib 包 可 用 在 Flask 程序 中 发 送 电子 邮件 ， 但 包装 了 smtplib 的 
Flask-Mail 扩展 能 更 好 地 和 Elask 集成 。 


使 用 Flask-Mail 提 供电 子 邮件 支持 





使 用 pip 安装 Flask-Mail: 


(venv) $ pip install flask-mail 

















Flask-Mail 连接 到 简单 邮件 传输 协议 (Simple Mail Transfer Protocol，SMTP) 服务 器 ， 并 











把 邮件 交 给 这 个 服务 器 发 送 。 如 果 不 进行 配置 ，Flask-Mail 会 连接 localhost 上 的 端口 25， 


无 需 验证 即 可 发 送 电子 邮件 。 表 6-1 列 出 了 可 用 来 设置 SMTP 服务 器 的 配置 。 


表 6-1 Flask-Mail SMTP 服 务 器 的 配置 
































配 置 默认 值 说 明 

MAIL_SERVER localhost 电子 邮件 服务 器 的 主机 名 或 IP 地 址 

HAT ORT 25 电子 邮件 服务 器 的 端口 

MAIL_USE_TLS False 启用 传输 层 安 全 (Transport Layer Security，TLS) 协议 
MAIL_USE_SSL False 启用 安全 套 接 层 (Secure Sockets Layer，SSL) 协议 
MAIL_USERNAME None 邮件 账户 的 用 户 名 

MAIL_PASSWORD None 邮件 账户 的 密码 
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在 开发 过 程 中 ， 如 果 连 接 到 外 部 SMTP 服务 器 ， 则 可 能 更 方便 。 举 个 例子 ， 示 例 6-1 展示 
了 如 何 配置 程序 ， 以 便 使 用 Google Gmail 账户 发 送 电子 邮件 。 


示例 6-1 hello.py: 配置 Flask-Mail 使 用 Gmail 


import os 

# ... 

app.config['MAIL_SERVER'] = 'smtp.googlemail.com' 
app.config['MAIL_PORT'] = 587 

app.config['MAIL_USE_TLS'] = True 

app.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME') 
app.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD') 


千 万 不 要 把 账户 密令 直接 写 入 脚本 ， 特 别 是 当 你 计划 开源 自己 的 作品 时 。 为 
了 保护 账户 信息 ， 你 需要 让 脚本 从 环境 中 导入 敏感 信息 。 





Flask-Mail 的 初始 化 方法 如 示例 6-2 所 示 。 


示例 6-2 ”hello.py: 初始 化 Flask-Mail 


from flask.ext.mail import Mail 
mail = Mail(app) 





保存 电子 邮件 服务 器 用 户 名 和 密码 的 两 个 环境 变量 要 在 环境 中 定义 。 如 果 你 在 Linux 或 
Mac OS X 中 使 用 bash， 那 么 可 以 按照 下 面 的 方式 设 定 这 两 个 变量 























(venv) $ export MAIL_USERNAME=<Gmail username> 
(venv) $ export MAIL_PASSWORD=<Gmail password> 





微软 Windows 用 户 可 按照 下 面 的 方式 设 定 环境 变量 











(venv) $ set MAIL_USERNAME=<Gmail Username> 
(venv) $ set MAIL_PASSWORD=<Gmail password> 


在 Python shell 中 发 送 电 子 邮 件 


你 可 以 打开 一 个 shell 会 话 ， 发 送 一 封 测试 邮件 ， 以 检查 配置 是 否 正 确 : 


(venv) $ python hello.py shell 
>>> from flask.ext.mail import Message 
>>> from hello import mail 
>>> msg = Message('test subject', sender="'you@Qexample.com', 
Ei recipients=['you@example.com']) 
>>> msg.body = 'text body' 
>>> msg.htmL = '<b>HTML</b> body' 
>>> with app.app_context(): 
mail.send(msg) 





注意 ，Flask-Mail 中 的 send() 函数 使 用 current_app， 因 此 要 在 激活 的 程序 上 下 文中 执行 。 


在 程序 中 集成 发 送 电子 邮件 功能 

为 了 避免 每 次 都 手动 编写 电子 邮件 消息 ， 我 们 最 好 把 程序 发 送 电子 邮件 的 通用 部 分 抽象 出 
来 ， 定 义 成 一 个 函数 。 这 么 做 还 有 个 好 处 ， 即 该 函数 可 以 使 用 Jinja2 模板 泻 染 邮件 正文 ， 
灵活 性 极 高 。 具 体 实现 如 示例 6-3 所 示 。 











示例 6-3 hello.py: 电子 邮件 支持 
from flask.ext.mail import Message 


app.config['FLASKY_MAIL_SUBJECT_PREFIX'] = '[Flasky]' 
app.config['FLASKY_MAIL_SENDER'] = "FLasky Admin <flasky@example.com>" 


def send_ email(to, subject, template, **kwargs): 
msg = Message(app.config['FLASKY_MAIL_SUBJECT_PREFIX'] + subject, 
sender=app.config['FLASKY_MAIL_SENDER'], recipients=[to]) 
msg.body = render_template(template + '.txt', **kwargs) 
msg.htmL = render_template(template + '.html', **kwargs) 
mail.send(msg) 


这 个 函数 用 到 了 两 个 程序 特定 配置 项 ， 分 别 定义 邮件 主题 的 前 级 和 发 件 人 的 地 址 。send_ 
email 函数 的 参数 分 别 为 收 件 人 人 地址、 主题 、 演 染 邮 件 正 文 的 模板 和 关键 字 参 数列 表 。 指 定 
模板 时 不 能 包含 扩展 名 ， 这 样 才能 使 用 两 个 模板 分 别 泻 染 纯 文本 正文 和 富 文 本 正文 。 调 用 者 
将 关键 字 参 数 传 给 render_template() 函数 ， 以 便 在 模板 中 使 用 ， 进 而 生成 电子 邮件 正文 。 


index() 视图 函数 很 容易 被 扩展 ， 这 样 每 当 表单 接收 新 名 字 时 ， 程 序 都 会 给 管理 员 发 送 一 
封 电 子 邮 件 。 修 改 方法 如 示例 6-4 所 示 。 











示例 6-4 ”hello.py: 电子 邮件 示例 
# ... 
app.config['FLASKY_ADMIN'] = os.environ.get('FLASKY_ADMIN') 
# ... 
@app.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate_on_submit(): 
user = User.query.filter_by(username=form.name.data).first() 
if user is None: 
User = User(username=form.name.data) 
db.session.add(user) 
session['known'] = False 
if app.config['FLASKY_ADMIN']: 
send_email(app.config['FLASKY_ADMIN'], 'New User ' ， 
'mail/new_user', user=user) 





else: 
session['known'] = True 
session['name'] = form.name.data 
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form.name.data = "" 
return redirect(url_for('index')) 
return render_template('index.html', form=form, name=session.get('name'), 
known=session.get('known', False)) 





电子 邮件 的 收 件 人 保存 在 环境 变量 FLASKY_ADMIN 中 ， 在 程序 启动 过 程 中 ， 它 会 加 载 到 一 个 
同名 配置 变量 中 。 我 们 要 创建 两 个 模板 文件 ， 分 别 用 于 泻 染 纯 文本 和 HTML 版 本 的 邮件 正 
文 。 这 两 个 模板 文件 都 保存 在 templates 文件 夹 下 的 mail 子 文件 夹 中 ， 以 便 和 普通 模板 区 
分 开 来 。 电 子 邮 件 的 模板 中 要 有 一 个 模板 参数 是 用 户 ， 因 此 调用 send_mail() 函数 时 要 以 
关键 字 参 数 的 形式 传 入 用 户 。 




















如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 9it checkout 
6a 签 出 程序 的 这 个 版 本 。 














除了 前 面 提 到 的 环境 变量 MAIL_USERNAME 和 MAIL_PASSWORD 之 外 ， 这 个 版 本 的 程序 还 需要 使 
用 环境 变量 FLASKY_ADMIN。Linux 和 Mac OS X 用 户 可 使 用 下 面 的 命令 添加 : 


























(venv) $ export FLASKY_ADMIN=<your-email-address> 
对 微软 Windows 用 户 来 说 ， 等 价 的 命令 是 : 
(venv) $ set FLASKY_ADMIN=<Gmail Username> 


设置 好 这 些 环境 变量 后 ， 我 们 就 可 以 测试 程序 了。 每 次 你 在 表单 中 填写 新 名 字 时 ， 管 理 员 
都 会 收 到 一 封 电子 邮件 。 


异步 发 送 电子 邮件 

如 果 你 发 送 了 几 封 测试 邮件 ， 可 能 会 注意 到 matl.send() 函数 在 发 送 电子 邮件 时 停滞 了 几 
秒 钟 ， 在 这 个 过 程 中 浏览 器 就 像 无 响应 一 样 。 为 了 避免 处 理 请 求 过 程 中 不 必要 的 延迟 ， 我 
们 可 以 把 发 送 电子 邮件 的 函数 移 到 后 台 线程 中 。 修 改 方法 如 示例 6-5 所 示 。 








上 

















人 


示例 6-5 hello.py: 异步 发 送 电 子 邮 伞 


from threading import Thread 


def send_async_email(app, msg): 
with app.app_context(): 
mail.send(msg) 


def send_email(to, subject, template, **kwargs): 
msg = Message(app.config['FLASKY_MAIL_ SUBJECT_PREFIX'] + subject, 
sender=app.config['FLASKY_MAIL_SENDER'], recipients=[to]) 
msg.body = render_template(template + '.txt', **kwargs) 





msg.html = render_tempLate(tempLate + '.html', **kwargs) 
thr = Thread(target=send_async_email, args=[app, msg]) 
thr.start() 

return thr 


上 述 实现 涉及 一 个 有 趣 的 问题 。 很 多 Flask 扩展 都 假设 已 经 存在 激活 的 程序 上 下 文 和 请 求 
上 下 文 。Flask-Mail 中 的 send() 函数 使 用 current_app， 因 此 必须 激活 程序 上 下 文 。 不 过 ， 
在 不 同 线程 中 执行 mail.send() 函数 时 ,程序 上 下 文 要 使 用 app.app_context() 人 工 创建 。 











如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 可 以 执行 qit checkout 6b 
签 出 程序 的 这 个 版 本 。 








现在 再 运行 程序 ， 你 会 发 现 程 序 流畅 多 了 。 不 过 要 记 住 ,程序 要 发 送 大 量 电子 邮件 时 ,使 
用 专门 发 送 电 子 邮件 的 作业 要 比 给 每 封 邮件 都 新 建 一 个 线程 更 合适 。 例 如 ， 我 们 可 以 把 执 
行 send_async_email() 函数 的 操作 发 给 Celery (http:/www.celeryproject.org/) 任务 队列 。 








至 此 ， 我 们 完成 了 对 大 多 数 Web 程序 所 需 功 能 的 概述 。 现 在 的 问题 是 ，hello.py 脚本 变 得 
越 来 越 大 ， 难 以 使 用 。 在 下 一 章 中 ， 你 会 学 到 如 何 组 织 大 型 程序 的 结构 。 
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第 7 章 





大 型 程序 的 结构 


尽管 在 单一 脚本 中 编写 小 型 Web 程序 很 方便 ， 但 这 种 方法 并 不 能 广泛 使 用 。 程 序 变 复杂 
后 ， 使 用 单个 大 型 源码 文件 会 导致 很 多 问题 。 


不 同 于 大 多 数 其 他 的 Web 框架 ，Flask 并 不 强制 要 求 大 型 项 目 使 用 特定 的 组 织 方式 ， 程 序 
结构 的 组 织 方式 完全 由 开发 者 决定 。 在 本 章 ， 我 们 将 介绍 一 种 使 用 包 和 模块 组 织 大 型 程序 


的 方式 。 本 了 





7.1 
Flask 程序 的 


示例 7-1 


后 续 示 例 都 将 采用 这 种 结构 。 


项 目 结构 


基本 结构 如 示例 7-1 所 示 。 


多 文件 Flask 程序 的 基本 结构 


| -fLasky 
|-app/ 


-tempLates/ 
-static/ 
-main/ 

-iMt .py 
| - 
|s 
EE 

-email.py 

-models.py 


errors.py 
forms.py 
Views.py 
init .py 


|-migrations/ 
|-tests/ 


init .py 


65 


| -testx .py 
-venv/ 
-requirements.txt 
-config.py 
-manage.py 


这 种 结构 有 4 个 顶级 文件 夹 : 


。 Flask 程序 一 般 都 保存 在 名 为 app 的 包 中 ， 

。 和 之 前 一 样 ，migrations 文件 夹 包含 数据 库 迁 移 脚 本 ， 
。 单元 测试 编写 在 tests 包 中 ， 

。 和 之 前 一 样 ，venv 文件 夹 包含 Python 虚拟 环境 。 














同时 还 创建 了 一 些 新 文件 : 














。 requirements.txt 列 出 了 所 有 依赖 包 ， 便 于 在 其 他 电脑 中 重新 生成 相同 的 虚拟 环境 ; 
。 config.py 存储 配置 ， 
。 manage.py 用 于 启动 程序 以 及 其 他 的 程序 任务 。 























为 了 帮助 你 完全 理解 这 个 结构 ， 下 面 几 市 讲解 把 hello.py 程序 转换 成 这 种 结构 的 过 程 。 


7.2 配置 选项 


程序 经 常 需要 设 定 多 个 配置 。 这 方面 最 好 的 例子 就 是 开发 、 测 试 和 生产 环境 要 使 用 不 同 的 
数据 库 ， 这 样 才 不 会 彼此 影响 。 

我 们 不 再 使 用 hello.py 中 简单 的 字典 状 结构 配置 ， 而 使 用 层次 结构 的 配置 类 。config.py 文 
件 的 内 容 如 示例 7-2 所 示 。 








示例 7-2 config.py: 程序 的 配置 


import os 
basedir = os.path.abspath(os.path.dirname(_ file  )) 





class Config: 
SECRET_KEY = os.environ.get('SECRET_KEY') or 'hard to guess string' 
SQLALCHEMY_COMMIT_ON_TEARDOWN = True 
FLASKY_MAIL_SUBJECT_PREFIX = '[Flasky]' 
FLASKY_MAIL_SENDER = 'Flasky Admin <flasky@example.com>" 
FLASKY_ADMIN = os.environ.get('FLASKY_ADMIN') 


@staticmethod 
def init_app(app): 
pass 


class DevelopmentConfig(Config): 
DEBUG = True 
MAIL_SERVER = 'smtp.googlemail .com' 
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MAIL_PORT = 587 

MAIL_USE_TLS = True 

MAIL_USERNAME = os.environ.get('MAIL_USERNAME') 

MAIL_PASSWORD = os.environ.get('MAIL_PASSWORD') 

SQLALCHEMY_DATABASE_URI = os.environ.get('DEV_DATABASE_URL') or \ 
'sqlite:///' + os.path.join(basedir, 'data-dev.sqlite') 


class TestingConfig(Config): 
TESTING = True 
SQLALCHEMY_DATABASE_URI = os.environ.get('TEST_DATABASE_URL') or \ 
'sqlite:///' + os.path.join(basedir, 'data-test.sqlite') 


class ProductionConfig(Config): 
SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE URL') or \ 
'sqlite:///' + os.path.join(basedir, 'data.sqlite') 


config = { 
"deveLopment ' : DevelopmentConfig, 
'testing': TestingConfig, 
'production': ProductionConfig, 


'default': DeveLopmentConfig 


} 

















基 类 Config 中 包含 通用 配置 ， 子 类 分 别 定义 专用 的 配置 。 如 果 需 要 ， 你 还 可 添加 其 他 配 
置 类 。 


为 了 让 配置 方式 更 灵活 且 更 安全 ， 某 些 配置 可 以 从 环境 变量 中 导入 。 例 如 ，SECRET_KEY 的 值 ， 
这 是 个 敏感 信息 ， 可 以 在 环境 中 设 定 ， 但 系统 也 提供 了 一 个 默认 值 ， 以 防 环境 中 没有 定义 。 














在 3 个 子 类 中 ，SQLALCHEMY_DATABASE_URI 变量 都 被 指定 了 不 同 的 值 。 这 样 程序 就 可 在 不 同 
的 配置 环境 中 运行 ， 每 个 环境 都 使 用 不 同 的 数据 库 。 











配置 类 可 以 定义 init_app() 类 方法 ， 其 参数 是 程序 实例 。 在 这 个 方法 中 ， 可 以 执行 对 当前 
环境 的 配置 初始 化 。 现 在 ， 基 类 Config 中 的 init_app() 方法 为 空 。 


在 这 个 配置 脚本 末尾 ，config 字典 中 注册 了 不 同 的 配置 环境 ， 而 且 还 注册 了 一 个 默认 配置 
(本 例 的 开发 环境 )。 


7.3 程序 包 


程序 包 用 来 保存 程序 的 所 有 代码 、 模 板 和 静态 文件 。 我 们 可 以 把 这 个 包 直 接 称 为 app (应 
用 )， 如 果 有 需求 ， 也 可 使 用 一 个 程序 专用 名 字 。templates 和 static 文件 夹 是 程序 包 的 一 部 
分 ， 因 此 这 两 个 文件 夹 被 移 到 了 app 中 。 数 据 库 模型 和 电子 邮件 支持 国 数 也 被 移 到 了 这 个 
包 中 ,分 别 保 存 为 app/models.py 和 app/email.py。 
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7.3.1 使 用 程序 工厂 函数 

在 单个 文件 中 开发 程序 很 方便 ， 但 却 有 个 很 大 的 缺点 ， 因 为 程序 在 全 局 作用 域 中 创建 ， 所 
以 无 法 动态 修改 配置 。 运 行 脚本 时 ， 程 序 实例 已 经 创建 ， 再 修改 配置 为 时 已 晚 。 这 一 点 对 
单元 测试 尤其 重要 ， 因 为 有 时 为 了 提高 测试 覆盖 度 ， 必 须 在 不 同 的 配置 环境 中 运行 程序 。 














这 个 问题 的 解决 方法 是 延迟 创建 程序 实例 ， 把 创建 过 程 移 到 可 显 式 调用 的 工厂 函数 中 。 这 
种 方法 不 仅 可 以 给 脚本 留 出 配置 程序 的 时 间 ， 还 能 够 创建 多 个 程序 实例 ， 这 些 实例 有 时 在 
测试 中 非常 有 用 。 程 序 的 工厂 函数 在 app 包 的 构造 文件 中 定义 ， 如 示例 7-3 所 示 。 


构造 文件 导入 了 大 多 数 正在 使 用 的 Flask 扩展 。 由 于 尚未 初始 化 所 需 的 程序 实例 ， 所 以 没 
有 初始 化 扩展 ， 创 建 扩展 类 时 没有 向 构造 函数 传人 参数 。create_app() 函数 就 是 程序 的 工 
厂 函 数 ， 接 受 一 个 参数 ， 是 程序 使 用 的 配置 名 。 配 置 类 在 config.py 文件 中 定义 ， 其 中 保存 
的 配置 可 以 使 用 Flask app.config 配置 对 象 提供 的 from_object() 方法 直接 导入 程序 。 至 
于 配置 对 象 ， 则 可 以 通过 名 字 从 config 字典 中 选择 。 程 序 创建 并 配置 好 后 ， 就 能 初始 化 
扩展 了 。 在 之 前 创建 的 扩展 对 象 上 调用 init_app() 可 以 完成 初始 化 过 程 。 


示例 7-3 app/_init .py: 程序 包 的 构造 文件 
from flask import Flask, render_template 
from flask.ext.bootstrap import Bootstrap 
from flask.ext.mail import Mail 
from flask.ext.moment import Moment 
from flask.ext.sqlalchemy import SQLALchemy 
from config import config 














bootstrap = Bootstrap() 
mail = Mail() 

moment = Moment() 

db = SQLALchemy() 


def create app(config_name): 
app = Flask(__name _) 
app.config.from object(config[config_name]) 
config[config name].init_app(app) 


bootstrap.init_app(app) 
mail.init_app(app) 
moment.init_app(app) 
db.init_app(app) 





# 附加 路 由 和 自 定义 的 错误 页 面 


return app 


工厂 函数 返回 创建 的 程序 示例 ， 不 过 要 注意 ， 现在 工厂 函数 创建 的 程序 还 不 完整 ， 因 为 没 
有 路 由 和 自 定义 的 错误 页 面 处 理 程序 。 这 是 下 一 节 要 讲 的 话题 。 





























7.3.2 ”在 蓝本 中 实现 程序 功能 

转换 成 程序 工厂 国 数 的 操作 让 定义 路 由 变 复杂 了 。 在 单 脚本 程序 中 ， 程 序 实 例 存 在 于 全 
局 作用 域 中 ， 路 由 可 以 直接 使 用 app.route 修饰 器 定义 。 但 现在 程序 在 运行 时 创建 ， 只 
有 调用 create_app() 之 后 才能 使 用 app.route 修饰 器 ， 这 时 定义 路 由 就 太 晚 了 。 和 路 由 
一 样 ， 自 定义 的 错误 页 面 处 理 程序 也 面临 相同 的 困难 ， 因 为 错误 页 面 处 理 程序 使 用 app. 
errorhandler 修饰 器 定义 。 
























































幸好 Flask 使 用 蓝本 提供 了 更 好 的 解决 方法 。 监 本 和 程序 类 似 ， 也 可 以 定义 路 由 。 不 同 的 
是 ， 在 蓝本 中 定义 的 路 由 处 于 休眠 状态 ， 直 到 蓝本 注册 到 程序 上 后 ， 路 由 才 真 正成 为 程序 
的 一 部 分 。 使 用 位 于 全 局 作用 域 中 的 蓝本 时 ， 定 义 路 由 的 方法 几乎 和 单 脚 本 程序 一 样 。 


和 程序 一 样 ， 蓝 本 可 以 在 单个 文件 中 定义 ， 也 可 使 用 更 结构 化 的 方式 在 包 中 的 多 个 模块 中 
创建 。 为 了 获得 最 大 的 灵活 性 ， 程 序 包 中 创建 了 一 个 子 包 ， 用 于 保存 蓝本 。 示 例 7-4 是 这 
个 子 包 的 构造 文件 ， 蓝 本 就 创建 于 此 。 














示例 7-4 app/main/_init .py: 创建 蓝本 
from flask import Blueprint 


main = Blueprint('main', __name_ ) 

from . import views, errors 
通过 实例 化 一 个 Blueprint 类 对 象 可 以 创建 蓝本 。 这 个 构造 函数 有 两 个 必须 指定 的 参数 : 
蓝本 的 名 字 和 蓝本 所 在 的 包 或 模块 。 和 程序 一 样 ， 大 多 数 情况 下 第 二 个 参数 使 用 Python 的 
_name_ 变量 即 可 。 
程序 的 路 由 保存 在 包 里 的 app/main/views.py 模块 中 ， 而 错误 处 理 程序 保存 在 app/main/ 
errors.py 模块 中 。 导 入 这 两 个 模块 就 能 把 路 由 和 错误 处 理 程序 与 蓝本 关联 起 来 。 注 意 ， 这 
些 模块 在 app/main/_init_.py 脚本 的 末尾 导入 ， 这 是 为 了 避免 循环 导入 依赖 ， 因 为 在 
views.py 和 errors.py 中 还 要 导入 蓝本 main。 























蓝本 在 工厂 函数 create_app() 中 注册 到 程序 上 ， 如 示例 7-5 所 示 。 


示例 7-5 app/_init_.py: 注册 蓝本 


def create_app(config_name): 


from .main import main as main_blueprint 
app.register_blueprint(main_blueprint) 


return app 














示例 7-6 显示 了 错误 处 理 程序 。 
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示例 7-6 app/main/errors.py: 蓝本 中 的 错误 处 理 程序 
from fLask import render_tempLate 
from . import main 





@main.app_errorhandler(404) 
def page_not_found(e): 
return render_template('404.html'), 404 


@main.app_errorhandler(500) 


def internal_server_error(e): 
return render_template('500.html'), 500 


在 蓝本 中 编写 错误 处 理 程序 稍 有 不 同 ， 如 果 使 用 errorhandler 修饰 器 ， 那 么 只 有 蓝本 中 的 
错误 才能 触发 处 理 程序 。 要 想 注册 程序 全 局 的 错误 处 理 程序 ， 必 须 使 用 app_errorhandler。 


在 蓝本 中 定义 的 程序 路 由 如 示例 7-7 所 示 。 


























示例 7-7 app/main/views.py: 蓝本 中 定义 的 程序 路 由 
from datetime import datetime 
from flask import render_template, session, redirect, url_for 


from . import main 

from .forms import NameForm 
from .. import db 

from ..models import User 


@main.route('/', methods=['GET', 'POST']) 
def index(): 
form = NameForm() 
if form.validate on_submit(): 
# ... 
return redirect(url_ for('.index')) 
return render_template('index.html', 
form=form, name=session.get('name'), 
known=session.get('known', False), 
current_ time=datetime.utcnow()) 


在 蓝本 中 编写 视图 函数 主要 有 两 点 不 同 : 第 一 ， 和 前 面 的 错误 处 理 程序 一 样 ， 路 由 修饰 器 
由 蓝本 提供 ;第 三 ，urt_for() 函数 的 用 法 不 同 。 你 可 能 还 记得 ，url_for() 函数 的 第 一 
个 参数 是 路 由 的 端点 名 ， 在 程序 的 路 由 中 ， 上 默认 为 视图 函数 的 名 字 。 例 如 ， 在 单 脚 本 程序 
中 ，index() 视图 函数 的 URL 可 使 用 url_for('index') 获取 。 





























在 蓝本 中 就 不 一 样 了 ，Flask 会 为 蓝本 中 的 全 部 端点 加 上 一 个 命名 空间 ， 这 样 就 可 以 在 不 
同 的 蓝本 中 使 用 相同 的 端点 名 定义 视图 函数 ， 而 不 会 产生 冲突 。 命 名 空间 就 是 蓝本 的 名 字 
(Blueprint 构造 函数 的 第 一 个 参数 )， 所 以 视图 函数 index() 注册 的 端点 名 是 main.index， 
其 URL 使 用 url_for('main.index') 获取 。 








url_for() 函数 还 支持 一 种 简写 的 端点 形式 ， 在 蓝本 中 可 以 省 略 蓝 本 名 ， 例 如 url_for('. 
index' )。 在 这 种 写法 中 ， 命 名 空间 是 当前 请 求 所 在 的 蓝本 。 这 意味 着 同一 蓝本 中 的 重 定向 
可 以 使 用 简写 形式 ， 但 跨 蓝本 的 重 定向 必须 使 用 带 有 命名 空间 的 端点 名 。 


为 了 完全 修改 程序 的 页 面 ， 表 单 对 象 也 要 移 到 蓝本 中 ， 保 存 于 app/main/forms.py 模块 。 


7.4 ”局 动 脚本 


顶级 文件 夹 中 的 manage.py 文件 用 于 启动 程序 。 脚 本 内 容 如 示例 7-8 所 示 。 











示例 7-8 manage.py: 启动 脚本 
#!/usr/bin/env python 
import os 
from app import create_app，db 
from app.modeLs import User, Role 
from flask.ext.script import Manager, Shell 
from flask.ext.migrate import Migrate, MigrateCommand 


app = create_app(os.getenv('FLASK_CONFIG') or 'default') 
manager = Manager(app) 
migrate = Migrate(app, db) 


def make_shell_context(): 
return dict(app=app, db=db, User=User, Role=Role) 
manager .add_command("shell", Shell(make_context=make_shell_context)) 
manager .add_command('db', MigrateCommand) 
if _ name == ' main _ 
manager .run() 


这 个 脚本 先 创建 程序 。 如 果 已 经 定义 了 环境 变量 FLASK_CONFIG， 则 从 中 读 取 配置 名 :否则 
使 用 默认 配置 。 然 后 初始 化 Flask-Script、Flask-Migrate 和 为 Python shell 定义 的 上 下 文 。 





出 于 便利 ， 脚 本 中 加 入 了 shebang 声明 ， 所 以 在 基于 Unix 的 操作 系统 中 可 以 通过 . /manage. 
py 执行 脚本 ， 而 不 用 使 用 复杂 的 python manage.py。 


7.5 ”需求 文件 

程序 中 必须 包含 一 个 requirements.txt 文件 ， 用 于 记录 所 有 依赖 包 及 其 精确 的 版 本 号 。 如 果 
要 在 另 一 台电 脑 上 重新 生成 虚拟 环境 ， 这 个 文件 的 重要 性 就 体现 出 来 了 ， 例 如 部 署 程序 时 
使 用 的 电脑 。pip 可 以 使 用 如 下 命令 自动 生成 这 个 文件 : 








(venv) $ pip freeze >requirements.txt 


安装 或 升级 包 后 ， 最 好 更 新 这 个 文件 。 需 求 文件 的 内 容 示 例如 下 : 
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FLask==0.10.1 
FLask-Bootstrap==3.0.3.1 
Flask-Mail==0.9.0 
Flask-Migrate==1.1.0 
Flask-Moment==0.2.0 
FLask-SQLALchemy==1.0 
Flask-Script==0.6.6 
FLask-NTF==0.9.4 
Jinja2==2.7.1 
Mako==0.9.1 
MarkupSafe==0.18 
SQLALchemy==0.8.4 
WTForms==1.0.5 
Werkzeug==0.9.4 
alembic==0.6.2 
blinker==1.3 
itsdangerous==0.23 


如 果 你 要 创建 这 个 虚拟 环境 的 完全 副本 ， 可 以 创建 一 个 新 的 虚拟 环境 ， 并 在 其 上 运行 以 下 


命令 : 





(venv) $ pip install -r requirements.txt 


当 你 阅读 本 书 时 ， 该 示例 requirements.txt 文件 中 的 版 本 号 可 能 已 经 过 期 了 。 如 果 愿 意 ， 你 
可 以 试 着 使 用 这 些 包 的 最 新 版 。 如 果 遇 到 问题 ， tt 文 个 需求 文件 中 的 版 本 ， 
因为 这 些 版 本 和 程序 兼容 。 


7.6 单元 测 试 


这 个 程序 很 小 ， 所 以 没什么 可 测试 的 。 不 过 为 了 演示 ， 我 们 可 以 编写 两 个 简单 的 测试 ， 如 
示例 7-9 所 示 。 














示例 7-9 ”tests/test_basics.py: 单元 测试 


import unittest 
from fLask import current_app 
from app import create_app，db 


class BasicsTestCase(unittest.TestCase): 
def setUp(self): 
self.app = create app('testing') 
self.app_context = self.app.app_context() 
self.app_context.push() 
db.create_all() 


def tearDown(self): 
db.session.remove() 
db.drop_all() 
self.app_context.pop() 


def test app_exists(self): 
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self.assertFalse(current_app is None) 


def test_app_is_testing(seLf) : 
self.assertTrue(current_app.config['TESTING']) 





这 个 测试 使 用 Python 标准 库 中 的 unittest 包 编 写 。setUp() 和 tearDown() 方法 分 别 在 各 
测试 前 后 运行 ， 并 且 名 字 以 test_ 开头 的 函数 都 作为 测试 执行 。 





如 果 你 想 进一步 了 解 如 何 使 用 Python 的 unittest 包 编 写 测试 ， 请 阅读 官方 文 
档 (https://docs.python.org/2/library/unittest.html) 。 


二 





setUp() 方法 尝试 创建 一 个 测试 环境 ， 类 似 于 运行 中 的 程序 。 首 先 ， 使 用 测试 配置 创建 程 
序 ， 然 后 激活 上 下 文 。 这 一 步 的 作用 是 确保 能 测试 中 使 用 current_app， 像 普通 请 求 一 
样 。 然 后 创建 一 个 全 新 的 数据 库 ， 以 备 不 时 之 需 。 数 据 库 和 程序 上 下 文 在 tearDown() 方法 
中 删除 。 


第 一 个 测试 确保 程序 实例 存在 。 第 二 个 测试 确保 程序 在 测试 配置 中 运行 。 若 想 把 tests 文 
件 夹 作为 包 使 用 ， 需 要 添加 tests/_init_.py 文件 ， 不 过 这 个 文件 可 以 为 空 ， 因 为 unittest 
包 会 扫描 所 有 模块 并 查找 测试 。 














如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， en 
7a 签 出 程序 的 这 个 版 本 。 为 确保 安装 了 所 有 依赖 包 ， 还 需 执行 ptp install 


-fr requirements .txt 命令 。 








为 了 运行 单元 测试 ， 你 可 以 在 manage.py 脚本 中 添加 一 个 自 定义 命令 。 示 例 7-10 展示 了 如 
何 添加 test 命令 。 


示例 7-10 ”manage.py: 启动 单元 测试 的 命令 
@manager .command 
def test(): 
'" "Run the unit tests.""" 
import unittest 
tests = unittest.TestLoader().discover('tests') 
unittest.TextTestRunner(verbosity=2).run(tests) 


manager .command 修饰 器 让 自 定义 命令 变 得 简单 。 修 饰 函 数 名 就 是 命令 名 ， 函 数 的 文档 字符 
串 会 显示 在 帮助 消息 中 。test() 函数 的 定义 体 中 调用 了 unittest 包 提 供 的 测试 运行 函数 。 

















单元 测试 可 使 用 下 面 的 命令 运行 : 
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(venv) $ python manage.py test 
test_app_exists (test_basics.BasicsTestCase) ... ok 
test_app_is_testing (test basics.BasicsTestCase) ... ok 


Ran 2 tests in 0.001s 


OK 


7.7 创建 数据 库 

重组 后 的 程序 和 单 脚 本 版 本 使 用 不 同 的 数据 库 。 

首选 从 环境 变量 中 读 取 数 据 库 的 URL， 同 时 还 提供 了 一 个 默认 的 SQLite 数据 库 做 备用 。3 
种 配置 环境 中 的 环境 变量 名 和 SQLite 数据 库 文 件 名 都 不 一 样 。 例 如 ， 在 开发 环境 中 ， 数 据 
库 URL 从 环境 变量 DEV_DATABASE_URL 中 读 取 ， 如 果 设 有 定义 这 个 环境 变量 ， 则 使 用 名 为 
data-dev.sqlite 的 SQLite 数据 库 。 


不 管 从 哪里 获取 数据 库 URL， 都 要 在 新 数据 库 中 创建 数据 表 。 如 果 使 用 Flask-Migrate 跟 
踪 迁 移 ， 可 使 用 如 下 命令 创建 数据 表 或 者 升级 到 最 新 修订 版 本 : 















































(venv) $ python manage.py db upgrade 


不 管 你 是 否 相信 ， 第 一 部 分 到 此 就 要 结束 了 。 现 在 你 已 经 学 到 了 使 用 Flask 开发 Web 程序 
的 用 备 基础 知识 ， 不 过 可 能 还 不 确定 如 何 把 这 些 知识 融 贯 起 来 开发 一 个 真正 的 程序 。 本 和 
第 二 部 分 的 目的 就 是 解决 这 个 问题 ， 带 着 你 一 步 一 步 地 开发 出 一 个 完整 的 程序 。 











而 








第 二 部 分 





实例 ; 社交 博客 程序 


第 8 和 章 


用 户 认 证 





大 多 数 程序 都 要 进行 用 户 跟踪 。 用 户 连 接 程 序 时 会 进行 身份 认证 ， 通 过 这 一 过 程 ， 让 程序 
知道 自己 的 身份 。 程 序 知 道 用 户 是 谁 后 ， 就 能 提供 有 针对 性 的 体验 。 


最 常用 的 认证 方法 要 求 用户 提 供 一 个 身份 证 明 (用 户 的 电子 邮件 或 用 户 名 ) 和 一 个 密码 。 
本 章 要 为 Flasky 开发 一 个 完整 的 认证 系统 。 


8.1 Flask 的 认证 扩展 


优秀 的 Python 认证 包 很 多 ， 但 没有 一 个 能 实现 所 有 功能 。 本 章 介 绍 的 认证 方案 使 用 了 多 个 
包 ， 并 编写 了 胶水 代码 让 其 良好 协作 。 本 章 使 用 的 包 列 表 如 下 。 




















。 Flask-Login: 管理 已 登录 用 户 的 用 户 会 话 。 
。 Werkzeug: 计算 密码 散 列 值 并 进行 核对 。 
。 itsdangerous: 生成 并 核对 加 密 安全 令 牌 。 


除了 认证 相关 的 包 之 外 ， 本 章 还 用 到 如 下 常规 用 途 的 扩展 。 


。 Flask-Mail: 发 送 与 认证 相关 的 电子 邮件 。 
。 Flask-Bootstrap: HTML 模板 。 
。 Flask-WTF: Web 表单 。 


8.2 密码 安全 性 
设计 Web 程序 时 ， 人 们 往往 会 高 估 数 据 库 中 用 户 信息 的 安全 性 。 如 果 攻 击 者 入 侵 服务 器 获 
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取 了 数据 库 ， 用 户 的 安全 就 处 在 风险 之 中 ， 这 个 风险 比 你 想象 的 要 大 。 众 所 周知 ， 大 多 数 
用 户 都 在 不 同 的 网 站 中 使 用 相同 的 密码 ， 因 此 ， 即 便 不 保存 任何 敏感 信息 ， 攻 击 者 获得 存 
储 在 数据 库 中 的 密码 之 后 ， 也 能 访问 用 户 在 其 他 网 站 中 的 账户 。 











若 想 保证 数据 库 中 用 户 密码 的 安全 ， 关 键 在 于 不 能 存储 密码 本 身 ， 而 要 存储 密码 的 散 列 
值 。 计 算 密 码 散 列 值 的 函数 接收 密码 作为 输入 ， 使 用 一 种 或 多 种 加 密 算法 转换 密码 ， 最 终 
得 到 一 个 和 原始 密码 没有 关系 的 字符 序列 。 核 对 密码 时 ， 密 码 散 列 值 可 代替 原始 密码 ， 
为 计算 散 列 值 的 函数 是 可 复 现 的 ， 只 要 输入 一 样 ， 结 果 就 一 样 。 

















计算 密码 散 列 值 是 个 复杂 的 任务 ， 很 难 正确 处 理 。 因 此 强烈 建议 你 不 要 自己 
实现 ， 而 是 使 用 经 过 社区 成 员 审查 且 声 誉 良好 的 库 。 如 果 你 对 生成 安全 密码 
散 列 值 的 过 程 感 兴 趣 , “Salted Password Hashing - Doing it Right” (计算 加 盐 
密码 散 列 值 的 正确 方法 ，https://crackstation.net/hashing-security.htm) 这 篇 文 
章 值得 一 读 。 








使 用 Werkzeug 实 现 密码 散 列 
Werkzeug 中 的 security 模块 能 够 很 方便 地 实现 密码 散 列 值 的 计算 。 这 一 功能 的 实现 只 需要 
两 个 函数 ， 分 别 用 在 注册 用 户 和 验证 用 户 阶段 。 





。 generate_password_hash(password,，method=pbkdf2:sha1，salt_length=8): 这 个 函数 将 
原始 密码 作为 输入 , 以 字符 串 形式 输出 密码 的 散 列 值 , 输出 的 值 可 保存 在 用 户 数据 库 中 。 
method 和 salt_length 的 默认 值 就 能 满足 大 多 数 需求 。 

。 check_password_hash(hash，password): 这 个 函数 的 参数 是 从 数据 库 中 取 回 的 密码 散 列 
值 和 用 户 输入 的 密码 。 返 回 值 为 True 表明 密码 正确 。 








示例 8-1 展示 了 第 5 章 创建 的 User 模型 为 支持 密码 散 列 所 做 的 改动 。 


示例 8-1 app/models.py: 在 User 模型 中 加 入 密码 散 列 


from werkzeug.security import generate password_hash, check_password_hash 


class User(db.Model): 
# ... 
password_hash = db.Column(db.String(128)) 


@property 
def password(self): 
raise AttributeError('password is not a readable attribute') 


@password.setter 
def password(self, password): 
self.password_hash = generate_ password_hash(password) 





def verify_password(self, password): 
return check_password_hash(self.password_hash, password) 


计算 密码 散 列 值 的 函数 通过 名 为 password 的 只 写 属 性 实现 。 设 定 这 个 属性 的 值 时 ， 赋 值 
方法 会 调用 Werkzeug 提供 的 generate_password_hash() 国 数 ， 并 把 得 到 的 结果 赋值 给 
password_hash 字段 。 如 果 试 图 读 取 password 属性 的 值 ， 则 会 返回 错误 ， 原 因 很 明显 ， 
为 生成 散 列 值 后 就 无 法 还 原 成 原来 的 密码 了 。 


verify_password 方 法 接受 一 个 参数 ( 即 密 码 )， 将 其 传 给 Werkzeug 提供 的 check_ 
password_hash() 函数 ， 和 存储 在 User 模型 中 的 密码 散 列 值 进行 比 对 。 如 果 这 个 方法 返回 
True， 就 表明 密码 是 正确 的 。 

















如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8a 签 出 程序 的 这 个 版 本 。 





密码 散 列 功能 已 经 完成 ， 可 以 在 shell 中 进行 测试 : 


(venv) $ python manage.py shell 

>>> U = User() 

>>> U.password = 'cat' 

>>> U.password_hash 
"pbkdf2:shal:10005duxMk00Fs4735b293e397d6eeaf650aaf490fd9091f928bed ' 
>>> U.Verify_password('cat') 


True 

>>> u.verify_password('dog') 
False 

>>> U2 = User() 

>>> U2.password = 'cat' 


>>> U2.password_hash 
'pbkdf2:sha1:1000$UjvnGeTP$875e28eb0874f44101d6b332442218f66975ee89' 


注意 ， 即 使 用 户 u 和 u2 使 用 了 相同 的 密码 ， 它 们 的 密码 散 列 值 也 完全 不 一 样 。 为 了 确保 
这 个 功能 今后 可 持续 使 用 ， 我 们 可 以 把 上 述 测 试 写成 单元 测试 ， 以 便于 重复 执行 。 我 们 要 
在 tests 包 中 新 建 一 个 模块 ， 编 写 3 个 新 测试 ， 测 试 最 近 对 User 模型 所 做 的 修改 ， 如 示例 
8-2 所 示 。 





示例 8-2 tests/test_user_model.py: 密码 散 列 化 测试 
import unittest 
from app.models import User 


class UserModelTestCase(unittest.TestCase): 
def test password_setter(self): 
U = User(password = 'cat') 
seLf .assertTrue(u.password_hash is not None) 
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def test_no_password_getter(seLf) : 


U = User(password = "cat ') 
with self.assertRaises(AttributeError): 
uy.password 


def test_ password verification(self): 
U = User(password = 'cat') 
seLf .assertTrue(u.Vverify_password('cat')) 
self.assertFalse(u.verify_password('dog')) 


def test password_salts_are_random(self): 
U = User(password='cat') 
U2 = User(password='cat') 
seLf .assertTrue(u.password_hash != u2.password_hash) 


母 和 4 
8.3 创建 认证 蓝 
我 们 在 第 7 章 介绍 过 蓝本 ， 把 创建 程序 的 过 程 移入 工厂 函数 后 ， 可 以 使 用 蓝本 在 全 局 作用 
域 中 定义 路 由 。 与 用 户 认 证 系统 相关 的 路 由 可 在 auth 蓝本 中 定义 。 对 于 不 同 的 程序 功能 ， 
我 们 要 使 用 不 同 的 蓝本 ， 这 是 保持 代码 整齐 有 序 的 好 方法 。 
auth 蓝本 保存 在 同名 Python 包 中 。 蓝 本 的 包 构 造 文件 创建 蓝本 对 人 象 ， 再 从 views.py 模块 
中 引入 路 由 ， 代 码 如 示例 8-3 所 示 。 





示例 8-3 app/auth/_init_.py: 创建 蓝本 
from fLask import BLueprint 


auth = Blueprint('auth', __name_ ) 


from . import views 


app/auth/views.py 模块 引入 蓝本 ， 然 后 使 用 蓝本 的 route 修饰 器 定义 与 认证 相关 的 路 由 ， 
如 示例 8-4 所 示 。 这 段 代 码 中 添加 了 一 个 /login 路 由 ， 演 染 同 名 占 位 模板 。 


示例 8-4 ”app/auth/views.py: 蓝本 中 的 路 由 和 视图 函数 
from fLask import render_tempLate 


from .import auth 


Qauth.route('/Login') 
def login(): 
return render_template('auth/login.html') 


注意 ， 为 render_template() 指定 的 模板 文件 保存 在 auth 文件 夹 中 。 这 个 文件 夹 必须 在 
app/templates 中 创建 ， 因 为 Flask 认为 模板 的 路 径 是 相对 于 程序 模板 文件 夹 而 言 的 。 为 避 
免 与 main 蓝本 和 后 续 添 加 的 蓝本 发 生 模板 命名 冲突 ， 可 以 把 蓝本 使 用 的 模板 保存 在 单独 的 
文件 夹 中 。 




















我 们 也 可 将 蓝本 配置 成 使 用 其 独立 的 文件 夹 保存 模板 。 如 果 配 置 了 多 个 模板 
文件 夹 ，render_template() 函数 会 首先 搜索 程序 配置 的 模板 文件 夹 ， 然 后 再 
搜索 蓝本 配置 的 模板 文件 夹 。 




















auth 蓝本 要 在 create_app() 工厂 函数 中 附加 到 程序 上 ， 如 示例 8-5 所 示 。 


示例 8-5 app/_init _.py: 附加 蓝本 
def create app(config name): 
i 
from .auth import auth as auth_blueprint 
app.register_blueprint(auth_blueprint, url_prefix="'/auth') 


return app 


注册 蓝本 时 使 用 的 urL_prefix 是 可 选 参 数 。 如 果 使 用 了 这 个 参数 ， 注 册 后 蓝本 中 定义 的 
所 有 路 由 都 会 加 上 指定 的 前 级 ， 即 这 个 例子 中 的 /auth。 例 如 ，/login 路 由 会 注册 成 /auth/ 
login， 在 开发 Web 服务 器 中 ， 完 整 的 URL 就 变 成 了 http://localhost:5000/auth/login。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8b 签 出 程序 的 这 个 版 本 。 





8.4 使 用 Flask-Login 认 证 用 户 


登录 程序 后 ， 他 们 的 认证 状态 要 被 记录 下 来 ， 这 样 浏览 不 同 的 页 面 时 才能 记 住 这 个 状 
= Flask-Login 是 个 非常 有 用 的 小 型 扩展 ， 专 门 用 来 管理 用 户 认 证 系统 中 的 认证 状态 ， 且 
不 依赖 特定 的 认证 机 制 。 


使 用 之 前 ， 我 们 要 在 虚拟 环境 中 安装 这 个 扩展 : 


(venv) $ pip install flask-login 


8.4.1 准备 用 于 登录 的 用 户 模型 
要 想 使 用 Flask-Login 扩展 ， 程 序 的 User 模型 必须 实现 几 个 方法 。 需 要 实现 的 方法 如 表 8-1 
所 示 。 
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表 8-1 ”Flask-Login 要 求实 现 的 用 户 方法 












































方 ”法 说 明 

is_authenticated() 如 果 用 户 已 经 登录 ， 必 须 返回 True， 否 则 返回 False 

is_active() 如 果 允 许 用 户 登录 ， 必 须 返回 True， 否 则 返回 Fatse。 如 果 要 禁用 账户 ， 可 以 返回 False 
is_anonymous() 对 普通 用 户 必须 返回 False 

get_id() 必须 返回 用 户 的 唯一 标识 符 ， 使 用 Unicode 编码 字符 串 














这 4 个 方法 可 以 在 模型 类 中 作为 方法 直接 实现 ， 不 过 还 有 一 种 更 简单 的 替代 方案 。EFlask- 
Login 提供 了 一 个 UserMixin 类 ， 其 中 包含 这 些 方 法 的 默认 实现 ， 且 能 满足 大 多 数 需求 。 修 
改 后 的 User 模型 如 示例 8-6 所 示 。 


示例 8-6 app/models.py: 修改 User 模型 ， 支 持 用 户 登录 


from flask.ext.login import UserMixin 


class User(UserMixin, db.Model): 
__tablename _ = 'Users' 
id = db.Column(db.Integer, primary_key = True) 
email = db.Column(db.String(64), unique=True, index=True) 
username = db.Column(db.String(64), unique=True, index=True) 
password_hash = db.Column(db.String(128)) 
role_id = db.Column(db.Integer, db.ForeignKey('roles.id')) 





注意 ， 示 例 中 同时 还 添加 了 email 字段 。 在 这 个 程序 中 ， 用 户 使 用 电子 邮件 地 址 登录 ， 
为 相对 于 用 户 名 而 言 ， 用 户 更 不 容易 忘记 自己 的 电子 邮件 地 址 。 


Flask-Login 在 程序 的 工厂 函数 中 初始 化 ， 如 示例 8-7 所 示 。 








示例 8-7 app/_init .py: 初始 化 Flask-Login 
from flask.ext.login import LoginManager 
login manager = LoginManager() 


login manager.session protection = 'strong’' 
login manager.login view = "auth.Login' 


def create app(config_name): 
# ... 
Login_manager .init_app(app) 
尖 


LoginManager 对 象 的 session_protection 属性 可 以 设 为 None、'basic' 或 'strong'， 以 提 
供 不 同 的 安全 等 级 防止 用 户 会 话 遭 自 改 。 设 为 "strong' 时 ，Flask-Login 会 记录 客户 端正 
地 址 和 浏览 器 的 用 户 代 理 信息 ， 如 果 发 现 异动 就 登 出 用 户 。login_view 属性 设置 登录 页 面 
的 端点 。 回 忆 一 下 ， 登 录 路 由 在 蓝本 中 定义 ， 因 此 要 在 前 面 加 上 蓝本 的 名 字 。 
































最 后 ，Flask-Login 要 求 程序 实现 一 个 回调 函数 ， 使 用 指定 的 标识 符 加 载 用 户 。 这 个 函数 的 
定义 如 示例 8-8 所 示 。 





示例 8-8 app/models.py: 加 载 用 户 的 回调 函数 
from . import login_manager 
@login_manager .user_loader 


def load_user(user_id): 
return User.query.get(int(user_id)) 


加 载 用 户 的 回调 函数 接收 以 Unicode 字符 串 形式 表示 的 用 户 标识 符 。 如 果 能 找到 用 户 ， 这 
个 函数 必须 返回 用 户 对 象 ， 否 则 应 该 返回 None。 


8.4.2 ”保护 路 由 
为 了 保护 路 由 只 让 认证 用 户 访问 ，Flask-Login 提供 了 一 个 login_required 修饰 器 。 用 法 演 
示 如 下 : 








from flask.ext.login import login_required 


@app.route('/secret') 
@login_required 
def secret(): 
return 'Only authenticated users are allowed!' 

















如 果 未 认证 的 用 户 访问 这 个 路 由 ，Flask-Login 会 拦截 请 求 ， 把 用 户 发 往 登 录 页 面 。 


8.4.3 添加 登录 表单 
呈现 给 用 户 的 登录 表单 中 包含 一 个 用 于 输入 电子 邮件 地 址 的 文本 字段 、 一 个 密码 字段 、 一 
个 “ 记 住 我 ” 复 选 框 和 提交 按钮 。 这 个 表单 使 用 的 Flask-WTF 类 如 示例 8-9 所 示 。 





示例 8-9 app/auth/forms.py: 登录 表单 


from flask.ext.wtf import Form 
from wtforms import StringField, PasswordField, BooleanField, SubmitField 
from wtforms.validators import Required, Length, Email 


class LoginForm(Form): 
email = StringField('Email', validators=[Required(), Length(1, 64), 
Email()]) 
password = PasswordField('Password', validators=[Required()]) 
remember_me = BooleanField('Keep me logged in') 
submit = SubmitField('Log In') 


电子 邮件 字段 用 到 了 WTForms 提供 的 Length() 和 Email() 验证 函数 。PasswordField 类 表 
示 属 性 为 type="password" 的 <input> 元 素 。BooleanField 类 表示 复 选 框 。 


登录 页 面 使 用 的 模板 保存 在 auth/login.html 文件 中 。 这 个 模板 只 需 使 用 Flask-Bootstrap 提 
供 的 wtf.quick_form() 宏 泻 染 表 单 妈 可 。 登 录 表 单 在 浏览 器 中 泻 染 后 的 样子 如 图 8-1 所 示 。 
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base.html 模板 中 的 导航 条 使 用 Jinja2 条 件 语 句 ， 并 根据 当前 用 户 的 登录 状态 分 别 显示 
“Sign mm” 或 “Sign Outf” 链 接 。 这 个 条 件 语句 如 示例 8-10 所 示 。 





示例 8-10 ”app/templates/base.html: 导航 条 中 的 Sign In 和 Sign Out 链接 


<ul class="nav navbar-nav navbar-right"> 
{% if current user.is authenticated() %} 
<li><a href="{{ url_for('auth.logout') }}">Sign Out</a></Li> 
{% else %} 
<li><a href="{{ url_for('auth.login') }}">Sign In</a></li> 
{% endif %} 

</ul> 





判断 条 件 中 的 变量 current_user 由 Flask-Login 定义 ， 且 在 视图 函数 和 模板 中 自动 可 用 。 
这 个 变量 的 值 是 当前 登录 的 用 户 ， 如 果 用 户 尚 未 登录 ， 则 是 一 个 匿名 用 户 代 理 对 象 。 如 果 


是 匿名 用 户 ，is_authenticated() 方法 返回 False。 所 以 这 个 方法 可 用 来 判断 当前 用 户 是 否 
已 经 登录 。 





























@ee Flasky - Login we 
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Keep me logged in 


Log In 








图 8-1 登录 表单 


8.4.4 登入 用 户 


视图 函数 Login() 的 实现 如 示例 8-11 所 示 。 





示例 8-11 app/auth/views.py: 登录 路 由 


from flask import render_template, redirect, request, url_for, flash 
from flask.ext.login import login_ user 








from . import auth 
from . .modeLs import User 
from .forms import LoginForm 


@auth.route('/login', methods=['GET', 'POST']) 
def login(): 
form = LoginForm() 
if form.validate_on_submit(): 
user = User.query.filter_by(email=form.email.data).first() 
if user is not None and user.verify_password(form.password.data): 
login_user(user, form.remember_me.data) 
return redirect(request.args.get('next') or url_for('main.index')) 
flash('Invalid username or password.') 
return render_template('auth/login.html', form=form) 








这 个 视图 函数 创建 了 一 个 LoginForm 对 象 ， 用 法 和 第 4 章 中 的 那个 简单 表单 一 样 。 当 请 
求 类 型 是 GET 时 ， 视 图 函数 直接 泻 染 模板 ， 即 显示 表单 。 当 表单 在 PoST 请 求 中 提交 时 ， 
Flask-WTF 中 的 validate_on_submit() 函数 会 验证 表单 数据 ， 然 后 尝试 登入 用 户 。 














为 了 登入 用 户 ， 视 图 函数 首先 使 用 表单 中 填写 的 email 从 数据 库 中 加 载 用 户 。 如 果 电 子 邮 
件 地 址 对 应 的 用 户 存 在 ， 再 调用 用 户 对 象 的 verify_password() 方法 ， 其 参数 是 表单 中 填 
写 的 密码 。 如 果 密 码 正确 ， 则 调用 Flask-Login 中 的 Login_user() 函数 ， 在 用 户 会 话 中 把 
用 户 标 记 为 已 登录 。Login_user() 函数 的 参数 是 要 登录 的 用 户 ， 以 及 可 选 的 “ 记 住 我 ” 布 
尔 值 ,，“ 记 住 我 ”也 在 表单 中 填写 。 如 果 值 为 False， 那 么 关闭 浏览 器 后 用 户 会 话 就 过 期 
了 ， 所 以 下 次 用 户 访问 时 要 重新 登录 。 如 果 值 为 True， 那 么 会 在 用 户 浏 览 器 中 写 入 一 个 长 
期 有 效 的 cookie， 使 用 这 个 cookie 可 以 复 现 用 户 会 话 。 





























按照 第 4 章 介绍 的 “Post 重 定向 /Get 模式 ”， 提 交 登 录 密 令 的 P0ST 请 求 最 后 也 做 了 重 定 
向 ， 不 过 目标 URL 有 两 种 可 能 。 用 户 访问 未 授权 的 URL 时 会 显示 登录 表单 ，Flask-Login 
会 把 原 地 址 保存 在 查询 字符 串 的 next 参数 中 ， 这 个 参数 可 从 request.args 字典 中 读 取 。 
如 果 查 询 字符 串 中 没有 next 参数 ， 则 重 定向 到 首页 。 如 果 用 户 输入 的 电子 邮件 或 密码 不 正 
确 ， 程 序 会 设 定 一 个 Flash 消息 ， 再 次 泻 染 表单 ， 让 用 户 重 试 登录 。 



































在 生产 服务 器 上 ， 登 录 路 由 必须 使 用 安全 的 HTTP， 从 而 加 密 传送 给 服务 器 
的 表单 数据 。 如 果 设 使 用 安全 的 HITP， 登 录 密 令 在 传输 过 程 中 可 能 会 被 截 
取 ， 在 服务 器 上 花 再 多 的 精力 用 于 保证 密码 安全 都 无 济 于 事 。 






































我 们 需要 更 新 登录 模板 以 渲染 表单 。 修 改 内 容 如 示例 8-12 所 示 。 





示例 8-12 ”app/templates/auth/login.html: 演 染 登录 表单 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 
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{% block title %}FLasky - Login{% endbLock %} 


{% block page_content %} 

<div class="page-header"> 
<h1>Login</h1> 

</div> 

<div class="col-md-4"> 
{{ wtf.quick_form(form) }} 

</div> 

{% endblock %} 


8.4.5” 登 出 用 户 


退出 路 由 的 实现 如 示例 8-13 所 示 。 


示例 8-13 app/auth/views.py: 退出 路 由 


from fLask.ext.Login import logout user, login required 


Qauth.route('/Logout ' ) 

@login_required 

def logout(): 
Logout_user() 
fLash('You have been Logged out.') 
return redirect(url_for('main.index')) 


为 了 登 出 用 户 ， 这 个 视图 函数 调用 Flask-Login 中 的 Logout_user() 函数 ， 删 除 并 重 设 用 户 
会 话 。 随 后 会 显示 一 个 Flash 消息 ， 确 认 这 次 操作 ， 再 重 定向 到 首页 ， 这 样 登 出 就 完成 了 。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8c 签 出 程序 的 这 个 版 本 。 这 次 更 新 包含 一 个 数据 库 迁 移 ， 所 以 签 出 代码 后 记 
得 要 运行 python manage.py db upgrade。 为 保证 安装 了 所 有 依赖 ， 你 还 要 运 
行 ptp install -r requtrements .txt。 








8.4.6 测试 登录 
为 验证 登录 功能 可 用 ， 可 以 更 新 首页 ， 使 用 已 登录 用 户 的 名 字 显 示 一 个 欢迎 消息 。 模 板 中 
生成 欢迎 消息 的 部 分 如 示例 8-14 所 示 。 








示例 8-14 ”app/templates/index.html: 为 已 登录 的 用 户 显示 一 个 欢迎 消息 
Hello, 
{% if current_user.is_authenticated() %} 
{{ current_user.username }} 
{% else %} 
Stranger 
{% endif %}! 

















在 这 个 模板 中 再 次 使 用 current_user.is_authenticated() 判断 用 户 是 否 已 经 登录 。 





因为 还 未 创建 用 户 注册 功能 ， 所 以 新 用 户 可 在 shell 中 注册 





(venv) $ python manage.py shell 


>>> U = User(email='john@example.com', username="'john', password='cat') 


>>> db.session.add(u) 
>>> db.session.commit() 


刚刚 创建 的 用 户 现在 可 以 登录 了 。 用 户 登录 后 显示 的 首页 如 图 8-2 所 


不 。 





Flasky 


eee se 和 
4 P|)| 人 | [+ | localhost:5000 


Hello, john! 














图 8-2 ”成功 登录 后 的 首页 


8.5 ”注册 新 用 户 


如 果 新 用 户 想 成 为 程序 的 成 员 ， 必 须 在 程序 中 注册 ， 这 样 程序 才能 认 


R 别 并 登 和 用户。 程序 








的 登录 页 面 中 要 显示 一 个 链接 ， 把 用 户 带 到 注册 页 面 ， 让 用 户 输入 电子 邮件 地 址 、 用 户 名 


和 密码 。 


8.5.1 添加 用 户 注册 表单 
注册 页 面 使 用 的 表单 要 求 用 户 输入 电子 邮件 地 址 、 用 户 名 和 密码 。 
所 示 。 











这 个 表单 如 示例 8-15 
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示例 8-15 app/auth/forms.py: 用 户 注册 表单 


from fLask.ext.wtf import Form 


from wtforms import StringField, PasswordField, BooleanField, SubmitField 
from wtforms.validators import Required, Length, Email, Regexp, EqualTo 


from wtforms import ValidationError 
from ..models import User 


class RegistrationForm(Form): 


email = StringField('Email', validators=[Required(), Length(1, 64), 


username 


Email()]) 


StringField('Username', validators=[ 


Required(), Length(1, 64), Regexp('^[A-Za-z][A-Za-z0-9_.]*$', 0, 


"Usernames must have only letters, 
'numbers, dots or underscores')]) 


password = PasswordField('Password', validators=[ 
Required(), EqualTo('password2', message='Passwords must match.')]) 
password2 = PasswordField('Confirm password', validators=[Required()]) 


submit = SubmitField('Register') 


def validate email(self, field): 


if User.query.filter_by(email=field.data).first(): 


def validate username(self, field): 


raise ValidationError('Email already registered.') 


if User.query.filter_by(username=field.data).first(): 


raise ValidationError('Username already in use.') 





这 个 表单 使 用 WTForms 提供 的 Regexp 验证 函数 ， 确 保 username 字段 只 包含 字母 、 数 字 、 


下 划 线 和 点 号 。 这 
证 失败 时 显示 的 错误 消息 。 





个 验证 函数 中 正则 表达 式 后 矣 








i 的 两 个 参数 分 别 是 正则 表达 式 的 旗 标 和 验 





安全 起 见 ， 密 码 要 输入 两 次 。 此 时 要 验证 两 个 密码 字段 中 的 值 是 否 一 致 ， 这 种 验证 可 使 用 
WTForms 提供 的 另 一 验证 函数 实现 ， 即 EqualTo。 这 个 验证 函数 要 附属 到 两 个 密码 字段 中 


的 一 个 上 ， 另 一 个 字段 则 作为 参数 传 入 。 


这 个 表单 还 有 两 个 自 定 义 的 验证 函数 ， 以 方法 的 形式 实现 。 如 果 表 单 类 中 定义 了 以 
validate_ 开头 且 后 面 跟着 字段 名 的 方法 ， 这 个 方法 就 和 常规 的 验证 函数 一 起 调用 。 本 例 
分 别 为 email 和 username 字段 定义 了 验证 函数 ， 确 保 填 写 的 值 在 数据 库 中 没 出 现 过 。 自 定 
义 的 验证 函数 要 想 表 示 验 证 失败 ， 可 以 抛 出 ValidationError 异常 ， 其 参数 就 是 错误 消息 。 





显示 这 个 表单 的 模板 是 /templates/auth/register.html。 和 登录 模板 一 样 ， 这 个 模板 也 使 用 


wtf.quick_form() 演 染 表单 。 注 册页 面 如 区 

















8-3 所 示 。 








e@ee Flasky - Register ww 
4 | [从] [+ [Clocalhost:5000 © Laeacec )[Q) 


Register 














8-3 ”新 用 户 注册 表单 


登录 页 面 要 显示 一 个 指向 注册 页 面 的 链接 ， 让 没有 账户 的 用 户 能 轻易 找到 注册 页 面 。 改 动 
如 示例 8-16 所 示 。 














示例 8-16 ”app/templates/auth/login.html: 链接 到 注册 页 本 
<p> 
New user? 
<a href="{{ url_for('auth.register') }}"> 
Click here to register 
</a> 
</p> 


8.5.2 ”注册 新 用 户 
处 理 用 户 注 册 的 过 程 没 有 什么 难以 理解 的 地 方 。 提 交 注 册 表 单 ， 通 过 验证 后 ， 系 统 就 使 用 
用 户 填写 的 信息 在 数据 库 中 添加 一 个 新 用 户 。 处 理 这 个 任务 的 视图 函数 如 示例 8-17 所 示 。 


























示例 8-17 app/auth/views.py: 用 户 注册 路 由 


@auth.route('/register', methods=['GET', 'POST']) 
def register(): 
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form = RegistrationForm() 
if form.vaLidate_on_submit() : 
user = User(email=form.email.data, 
username=form.username.data, 
password=form.password.data) 
db.session.add(user) 
flash('You can now login.') 
return redirect(url_for('auth.login')) 
return render_template('auth/register.html', form=form) 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8d 签 出 程序 的 这 个 版 本 。 














8.6 确认 账户 


对 于 某 些 特定 类 型 的 程序 ， 有 必要 确认 注册 时 用 户 提供 的 信息 是 否 正确 。 常 见 要 求 是 能 通 
过 提供 的 电子 邮件 地 址 与 用 户 取 得 联系 。 








为 验证 电子 邮件 地 址 ， 用 户 注册 后 ， 程 序 会 立即 发 送 一 封 确认 邮件 。 新 账户 先 被 标记 成 待 
确认 状态 ， 用 户 按照 邮件 中 的 说 明 操 作 后 ， 才 能 证 明 自己 可 以 被 联系 上 。 账 户 确 认 过 程 
中 ， 往 往 会 要 求 用 户 点 击 一 个 包含 确认 令 牌 的 特殊 URL 链接 。 





8.6.1 使 用 itsdangerous 生 成 确认 令 牌 

确认 邮件 中 最 简单 的 确认 链接 是 http:/www.example.com/auth/confirm/<id> 这 种 形式 的 
URL， 其 中 这 是 数据 库 分 配给 用 户 的 数字 tid。 用 户 点 击 链接 后 ， 处 理 这 个 路 由 的 视图 函 
数 就 将 收 到 的 用 户 id 作为 参数 进行 确认 ， 然 后 将 用 户 状态 更 新 为 已 确认 。 

















但 这 种 实现 方式 显然 不 是 很 安全 ， 只 要 用 户 能 判断 确认 链接 的 格式 ， 就 可 以 随便 指定 URL 
中 的 数字 ， 从 而 确认 任意 账户 。 解 决 方法 是 把 URL 中 的 记 换 成 将 相同 信息 安全 加 密 后 得 
到 的 令 牌 。 

回忆 一 下 我 们 在 第 4 章 对 用 户 会 话 的 讨论 ，Flask 使 用 加 密 的 签名 cookie 保护 用 户 会 话 ， 
防止 被 自 改 。 这 种 安全 的 cookie 使 用 itsdangerous 包 签 名 。 同 样 的 方法 也 可 用 于 确认 令 
牌 上 。 





下 面 这 个 简短 的 shell 会 话 显示 了 如 何 使 用 itsdangerous 包 生 成 包含 用 户 id 的 安全 令 牌 : 


(venv) $ python manage.py shell 
>>> from manage import app 
>>> from itsdangerous import TimedJSONWebSignatureSerializer as Serializer 





>>> s = Serializer(app.config['SECRET_KEY'], expires_in = 3600) 

>>> token = s.dumps({ 'confirm': 23 }) 

>>> token 
"eyJhbaciOtiJIUzI1NLISImV4CCI6MTM4MTCxODU10CwiLaNF0IjoxMzgxNzEOOTU4fQ.ey ...，' 
>>> data = s.Loads(token) 

>>> data 

{u'confirm': 23} 


itsdangerous 提供 了 多 种 生成 令 牌 的 方法 。 其 中 ，TimedJSONWebSignatureSerializer 类 生成 
具有 过 期 时 间 的 JSON Web 签名 (JSON Web Signatures，JWS)。 这 个 类 的 构造 国 数 接收 
的 参数 是 一 个 密 钥 ， 在 Flask 程序 中 可 使 用 SECRET_KEY 设置 。 





dumps() 方法 为 指定 的 数据 生成 一 个 加 密 签名 ， 然 后 再 对 数据 和 签名 进行 序列 化 ， 生 成 令 
牌 字符 种 。exptres_in 参数 设置 令 牌 的 过 期 时 间 ， 单 位 为 秒 。 




















为 了 解码 令 牌 ， 序 列 化 对 象 提供 了 Loads() 方法 ， 其 唯一 的 参数 是 令 牌 字符 串 。 这 个 方法 
会 检验 签名 和 过 期 时 间 ， 如 果 通 过 ， 返 回 原始 数据 。 如 果 提 供给 loads() 方法 的 令 牌 不 正 
确 或 过 期 了 ， 则 抛 出 异常 。 


Ud 





我 们 可 以 将 这 种 生成 和 检验 令 牌 的 功能 可 添加 到 User 模型 中 。 改 动 如 示例 8-18 所 示 。 


示例 8-18 ”app/models.py: 确认 用 户 账户 


from itsdangerous import TimedJSONWebSignatureSerializer as Serializer 
from flask import current_app 
from . import db 


class User(UserMixin, db.Model): 
A 5 
confirmed = db.Column(db.Boolean, default=False) 


def generate_confirmation_token(self, expiration=3600): 
s = Serializer(current app.config['SECRET_KEY'], expiration) 
return s.dumps({'confirm': self.id}) 


def confirm(self, token): 
s = Serializer(current _app.config['SECRET_KEY']) 
try: 
data = s.Loads(token) 
except: 
return False 
if data.get('confirm') != self.id: 
return False 
self.confirmed = True 
db.session.add(self) 
return True 


generate_confirmation_token() 方法 生成 一 个 令 牌 ， 有 效 期 默认 为 一 小 时 。confirm() 方 
法 检验 令 牌 ， 如果 检 验 通 过 ， 则 把 新 添加 的 confirmed 属性 设 为 True。 
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除了 检验 令 牌 ，confirm() 方法 还 检查 令 牌 中 的 id 是否 和 存储 在 current_user 中 的 已 登录 
用 户 匹配 。 如 此 一 来 ， 即 使 恶意 用 户 知道 如 何 生 成 签名 令 牌 ， 也 无 法 确认 别人 的 账户 。 











由 于 模型 中 新 加 入 了 一 个 列 用 来 保存 账户 的 确认 状态 ， 因 此 要 生成 并 执行 一 
个 新 数据 库 迁 移 。 














User 模型 中 新 添加 的 两 个 方法 很 容易 进行 单元 测试 。 你 可 以 在 这 个 程序 的 GitHub 仓库 中 
找到 单元 测试 。 


8.6.2 发 送 确认 邮件 
当前 的 /register 路 由 把 新 用 户 添加 到 数据 库 中 后 ， 会 重 定 向 到 /index。 在 重 定向 之 前 ， 这 
个 路 由 需要 发 送 确认 邮件 。 改 动 如 示例 8-19 所 示 。 


示例 8-19 app/auth/views.py: 能 发 送 确 认 邮 件 的 注册 路 由 


from . .emaiL import send_email 


@auth.route('/register', methods = ['GET', 'POST']) 
def register(): 
form = RegistrationForm() 
if form.validate on_submit(): 
# ... 
db.session.add(user) 
db.session.commit() 
token = user.generate confirmation_ token() 
send_email(user .email, 'Confirm Your Account ' ， 
'auth/email/confirm', user=user, token=token) 
flash('A confirmation email has been sent to you by email.') 
return redirect(url_ for('main.index')) 
return render_template('auth/register.html', form=form) 


注意 ， 即 便 通 过 配置 ， 程 序 已 经 可 以 在 请 求 末尾 自动 提交 数据 库 变化 ， 这 里 也 要 添加 
db.session.commit() 调用 。 问 题 在 于 ， 提 交 数 据 库 之 后 才能 赋予 新 用 户 id 值 ， 而 确认 令 
牌 需要 用 到 id， 所 以 不 能 延 后 提交 。 





认证 蓝本 使 用 的 电子 邮件 模板 保存 在 templates/auth/email 文件 夹 中 ， 以 便 和 HTML 模板 
区 分 开 来 。 第 6 章 介 绍 过 ,一 个 电子 邮件 需要 两 个 模板 ,分 别 用 于 演 染 纯 文本 正文 和 富 
文本 正文 。 举 个 例子 ， 示 例 8-20 是 确认 邮件 模板 的 纯 文本 版 本 ， 对 应 的 HTML 版 本 可 到 
GitHub 仓库 中 查看 。 








示例 8-20 ”app/templates/auth/email/confirm.txt: 确认 邮件 的 纯 文本 正文 


Dear {{ user.username }}, 





Welcome to Flasky! 

To confirm your account please click on the following link: 
{{ url_for('auth.confirm', token=token, _external=True) }} 
Sincerely, 

The Flasky Team 


Note: replies to this email address are not monitored. 


默认 情况 下 ，urtL_for() 生成 相对 URL， 例 如 urL_for('auth.confirm'，token='abc') 返 
回 的 字符 串 是 '/auth/confirm/abc'。 这 显然 不 是 能 够 在 电子 邮件 中 发 送 的 正确 URL。 相 
对 URL 在 网 页 的 上 下 文中 可 以 正常 使 用 ， 因 为 通过 添加 当前 页 面 的 主机 名 和 端口 号 ， 误 
览 器 会 将 其 转换 成 绝对 URL。 但 通过 电子 邮件 发 送 URL 时 ， 并 没有 这 种 上 下 文 。 添 加 到 
url_for() 函数 中 的 _external=True 参数 要 求 程序 生成 完整 的 URL， 其 中 包含 协议 (http:// 
或 https://)、 主 机 名 和 端口 。 

















确认 账户 的 视图 函数 如 示例 8-21 所 示 。 


示例 8-21 app/auth/views.py: 确认 用 户 的 账户 


from flask.ext.login import current_user 


@auth.route('/confirm/<token>') 
@login_required 
def confirm(token): 
if current_user.confirmed: 
return redirect(url_for('main.index')) 
if current_user.confirm(token): 
flash('You have confirmed your account. Thanks!') 
else: 
flash('The confirmation link is invalid or has expired.') 
return redirect(url_for('main.index')) 


Flask-Login 提供 的 login_required 修饰 器 会 保护 这 个 路 由 ， 因 此 ， 用 户 点 击 确认 邮件 中 的 
链接 后 ， 要 先 登 录 ， 然 后 才能 执行 这 个 视图 函数 。 














这 个 函数 先 检查 已 登录 的 用 户 是 否 已 经 确认 过 ， 如 果 确 认 过 ， 则 重 定向 到 首页 ， 因 为 很 
显然 此 时 不 用 做 什么 操作 。 这 样 处 理 可 以 避免 用 户 不 小 心 多 次 点 击 确认 令 牌 带 来 的 额外 
工作 。 








由 于 令 牌 确认 完全 在 User 模型 中 完成 ， 所 以 视图 函数 只 需 调用 confirm() 方法 即 可 ， 然 后 
再 根据 确认 结果 显示 不 同 的 Flash 消息 。 确 认 成 功 后 ，User 模型 中 confirmed 属性 的 值 会 
被 修改 并 添加 到 会 话 中 ， 请 求 处 理 完 后 ， 这 两 个 操作 被 提交 到 数据 库 。 


每 个 程序 都 可 以 决定 用 户 确认 账户 之 前 可 以 做 哪些 操作 。 比 如 ， 人 允许 未 确认 的 用 户 登 录 ， 
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但 只 显示 一 个 页 面 ， 这 个 页 面 要 求 用 户 在 获取 权限 之 前 先 确认 账户 。 




















这 一 步 可 使 用 Flask 提供 的 before_request 钩子 完成 ， 我 们 在 第 2 章 就 已 经 简单 介绍 过 钧 
子 的 相关 内 容 。 对 蓝本 来 说 ，before_request 钩子 只 能 应 用 到 属于 蓝本 的 请 求 上 。 若 想 在 
蓝本 中 使 用 针对 程序 全 局 请 求 的 钩子 ， 必 须 使 用 before_app_request 修饰 器 。 示 例 8-22 展 
示 了 如 何 实现 这 个 处 理 程 序 。 





























示例 8-22 ”app/auth/views.py: 在 before_app_request 处 理 程序 中 过 滤 未 确认 的 账户 


@auth.before_app_request 
def before_request(): 
if current_user.is_authenticated() \ 
and not current_user.confirmed \ 
and request.endpoint[:5] != "auth.': 
and request.endpoint != 'static': 
return redirect(url_for('auth.unconfirmed')) 





@auth.route('/unconfirmed') 
def unconfirmed(): 
if current_user.is_anonymous() or current_user.confirmed: 
return redirect(url_ for('main.index')) 
return render_template('auth/unconfirmed.html') 


同时 满足 以 下 3 个 条 件 时 ，before_app_request 处 理 程序 会 拦截 请 求 。 





(1) 用 户 已 登录 (current_user.is_authenticated() 必须 返回 True) 。 

(2) 用 户 的 账户 还 未 确认 。 

(3) 请 求 的 端点 (使 用 request.endpoint 获取 ) 不 在 认证 蓝本 中 。 访 问 认 证 路 由 要 获取 权 
限 ， 因 为 这 些 路 由 的 作用 是 让 用 户 确认 账户 或 执行 其 他 账户 管理 操作 。 


如 果 请 求 满足 以 上 3 个 条 件 ， 则 会 被 重 定向 到 /auth/unconfirmed 路 由 ， 显 示 一 个 确认 账户 
相关 信息 的 页 面 。 





如 果 before_request 或 before_app_request 的 回调 返回 啊 应 或 重 定向 ，Flask 
会 直接 将 其 发 送 至 客户 端 ， 而 不 会 调用 请 求 的 视图 函数 。 因 此 ， 这 些 回调 可 
在 必要 时 拦截 请 求 。 




















示 给 未 确认 用 户 的 页 面 (如 图 8-4 所 示 ) 只 演 染 一 个 模板 ， 其 中 有 如 何 确认 账户 的 说 明 ， 
此 外 还 提供 了 一 个 链接 ， 用 于 请 求 发 送 新 的 确认 邮件 ， 以 防 之 前 的 邮件 丢失 。 重 新 发 送 确 
认 邮 件 的 路 由 如 示例 8-23 所 示 。 








示例 8-23 ”app/auth/views.py: 重新 发 送 账户 确认 邮件 
@auth.route('/confirm') 
@login_required 
def resend_confirmation(): 








token = current_user.generate_confirmation_token() 
send_email(current user.email, 'Confirm Your Account', 

'auth/email/confirm', user=current_user, token=token) 
flash('A new confirmation email has been sent to you by email.') 
return redirect(url_for('main.index')) 





这 个 路 由 为 current_user ( 即 已 登录 的 用 户 ， 也 是 目标 用 户 ) 重 做 了 一 遍 注 册 路 由 中 的 操 
作 。 这 个 路 由 也 用 Login_required 保护 ， 确 保 访 问 时 程序 知道 请 求 再 次 发 送 邮件 的 是 哪个 
用 户 。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
8e 签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 所 以 签 出 代码 后 要 
执行 python manage.py db upgrade。 














@ee Flasky - Confirm your accont 


4 >)[ 人 [+ | localhost:5000 


Hello, john! 


You have not confirmed your account yet. 


Before you can access this site you need to confirm your account. Check your inbox, you should have received an 
email with a confirmation link. 


Need another confirmation email? Click here 














8-4 未 确认 账户 页 面 


8.7 ”管理 账户 


拥有 程序 账户 的 用 户 有 时 可 能 需要 修改 账户 信息 。 下 面 这 些 操作 可 使 用 本 章 介绍 的 技术 添 
加 到 验证 蓝本 中 。 





修改 密码 

安全 意识 强 的 用 户 可 能 希望 定期 修改 密码 。 这 是 一 个 很 容易 实现 的 功能 ， 只 要 用 户 处 于 
登录 状态 ， 就 可 以 放心 显示 一 个 表单 ， 要 求 用 户 输入 旧 密 码 和 替换 的 新 密码 。( 这 个 功 
能 的 实现 参见 GitHub 仓库 中 标签 为 8f 的 提交 。) 
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重 设 密码 

为 避免 用 户 忘记 密码 无 法 登入 的 情况 ， 程 序 可 以 提供 重 设 密码 功能 。 安 全 起 见 ， 有 必要 
使 用 类 似 于 确认 账户 时 用 到 的 令 牌 。 用 户 请 求 重 设 密码 后 ， 程 序 会 向 用 户 注册 时 提供 的 
电子 邮件 地 址 发 送 一 封包 含 重 设 令 牌 的 邮件 。 用 户 点 击 邮件 中 的 链接 ， 令 牌 验证 后 ， 会 
显示 一 个 用 于 输入 新 密码 的 表单 。( 这 个 功能 的 实现 参见 GitHub 仓库 中 标签 为 89 的 提 


交 。) 





修改 电子 邮件 地 址 

程序 可 以 提供 修改 注册 电子 邮件 地 址 的 功能 ， 不 过 接受 新 地 址 之 前 ， 必 须 使 用 确认 邮 们 
进行 验证 。 使 用 这 个 功能 时 ， 用 户 在 表单 中 输入 新 的 电子 邮件 地 址 。 为 了 验证 这 个 地 
址 ， 程 序 会 发 送 一 封包 含 令 牌 的 邮件 。 服 务 器 收 到 令 牌 后 ， 再 更 新 用 户 对 象 。 服 务 器 收 
到 令 牌 之 前 ， 可 以 把 新 电子 邮件 地 址 保存 在 一 个 新 数据 库 字 段 中 作为 待定 地 址 ， 或 者 将 
其 和 id 一 起 保存 在 令 牌 中 。( 这 个 功能 的 实现 参见 GitHub 仓库 中 标签 为 8h 的 提交 。) 


I 














下 一 章 ， 我 们 使 用 用 户 角 色 扩 充 Flasky 的 用 户 子 系统 。 





第 9 章 


用 户 角色 





Web 程序 中 的 用 户 并 非 都 具有 同样 地 位 。 在 大 多 数 程序 中 ， 一 小 部 分 可 信用 户 具 有 额外 权 
限 ， 用 于 保证 程序 平稳 运行 。 管 理 员 就 是 最 好 的 例子 ， 但 有 时 也 需要 介 于 管理 员 和 普通 用 
户 之 间 的 角色 ， 例 如 内 容 协 管 员 。 





有 多 种 方法 可 用 于 在 程序 中 实现 角色 。 有 具体 采用 何 种 实现 方法 取决 于 所 需 角 色 的 数量 和 细 
分 程度 。 例 如 ， 简 单 的 程序 可 能 只 需要 两 个 角色 ， 一 个 表示 普通 用 户 ， 一 个 表示 管理 员 。 
对 于 这 种 情况 ， 在 User 模型 中 添加 一 个 is_administrator 布尔 值 字段 就 足够 了 。 复 杂 的 
程序 可 能 需要 在 普通 用 户 和 管理 员 之 间 再 细 分 出 多 个 不 同等 级 的 角色 。 有 些 程序 甚至 不 能 
使 用 分 立 的 角色 ， 这 时 赋予 用 户 某 些 权限 的 组 合 或 许 更 合适 。 


本 章 介 绍 的 用 户 角色 实现 方式 结合 了 分 立 的 角色 和 权限 ,赋予 用 户 分 立 的 角色 ,但 角色 使 
用 权限 定义 。 


9.1 角色 在 数据 库 中 的 表示 


第 5 章 创建 了 一 个 简单 的 roles 表 ， 用 来 演示 一 对 多 关系 。 示 例 9-1 是 改进 后 的 Role 模型 。 


















































示例 9-1 app/models.py: 角色 的 权限 


class Role(db.Model): 
_ tabLename_ = 'roles' 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String(64), unique=True) 
default = db.Column(db.Boolean, default=False, index=True) 
permissions = db.CoLumn(db.Integer) 
users = db.relationship('User', backref='role', lazy='dynamic') 
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只 有 一 个 角色 的 default 字段 要 设 为 True， 其 他 都 设 为 Fatse。 用 户 注册 时 ， 其 角色 会 被 
设 为 默认 角色 。 


这 个 模型 的 第 二 处 改动 是 添加 了 permissions 字段 ， 其 值 是 一 个 整数 ， 表 示 位 标志 。 各 操 
作 都 对 应 一 个 位 位 置 ， 能 执行 某 项 操作 的 角色 ， 其 位 会 被 设 为 1。 














显然 ， 各 操作 所 需 的 程序 权限 是 不 一 样 的 。 对 Flasky 开 说 ， 各 种 操作 如 表 9-1 所 示 。 
表 9-1 程序 的 权限 






























































二 从 位 > 值 说 明 

关注 用 户 0b00000001 (0Ox01) 关注 其 他 用 户 

在 他 人 的 文章 中 发 表 评 论 0b00000010 (0x02) 在 他 人 撰写 的 文章 中 发 布 评论 
写 文章 0b00000100 (0x04) 写 原 创 文章 

管理 他 人 发 表 的 评论 0b00001000 (Ox08) 查处 他 人 发 表 的 不 当 评 论 
管理 员 权限 0b10000000 (Ox80) 管理 网 站 





注意 ， 操 作 的 权限 使 用 8 位 表示 ， 现 在 只 用 了 其 中 5 位 ， 其 他 3 位 可 用 于 将 来 的 扩充 。 
表 9-1 中 的 权限 可 使 用 示例 9-2 中 的 代码 表示 。 





示例 9-2 ”app/models.py: 权限 常量 
class Permission: 
FOLLOW = 0x01 
COMMENT = 0x02 
WRITE_ARTICLES = 0x04 
MODERATE_COMMENTS = 0x08 
ADMINISTER = 0x80 


表 9-2 列 出 了 要 支持 的 用 户 角 色 以 及 定义 角色 使 用 的 权限 位 。 





表 9-2 用户 角色 

用 户 角色 权 限 说 明 

匿名 0b00000000 (0x00) 未 登录 的 用 户 。 在 程序 中 只 有 阅读 权限 
户 0b00000111 (0x07) 具有 发 布 文章 、 发 表 评论 和 关注 其 他 用 户 的 权限 。 这 是 新 用 户 的 默认 角色 

协 管 员 0b00001111 (0x0f) ”增加 审查 不 当 评论 的 权限 

管理 员 ”0b11111111 (0xff) ”上 有 具有 所 有 权限 ， 包 括 修改 其 他 用 户 所 属 角 色 的 权限 
























































使 用 权限 组 织 角色 ， 这 一 做 法 让 你 以 后 添加 新 角色 时 只 需 使 用 不 同 的 权限 组 合 即 可 。 


将 角色 手动 添加 到 数据 库 中 既 耗 时 又 容易 出 错 。 作 为 替代 ， 我 们 要 在 Role 类 中 添加 一 个 类 
方法 ， 完 成 这 个 操作 ， 如 示例 9-3 所 示 。 


示例 9-3 ”app/models.py:: 在 数据 库 中 创建 角色 


class Role(db.Model): 











# ... 


@staticmethod 
def insert_roles(): 
roles = { 


for 


'User': (Permission.FOLLOW | 
Permission.COMMENT | 
Permission.WRITE_ARTICLES, True), 
'Moderator': (Permission.FOLLOW | 
Permission.COMMENT | 
Permission.WRITE_ARTICLES | 
Permission.MODERATE_COMMENTS, False), 
'Administrator': (Oxff, False) 


r in roles: 
role = Role.query.filter_by(name=r).first() 
if role is None: 

role = Role(name=r) 
role.permissions = roLes[r][0] 
role.default = roles[r][1] 
db.session.add(role) 


db.session.commit() 


insert_roles() 函数 并 不 直接 创建 新 角色 对 象 ， 而 是 通过 角色 名 查找 现 有 的 角色 ， 然 后 再 
进行 更 新 。 只 有 当 数 据 库 中 没有 某 个 角色 名 时 才 会 创建 新 角色 对 象 。 如 此 一 来 ， 如 果 以 后 
更 新 了 角色 列表 ， 就 可 以 执行 更 新 操作 了 。 要 想 添 加 新 角色 ， 或 者 修改 角色 的 权限 ， 修 改 


roles 数组 ， 再 运行 函数 即 可 。 注 意 ，“ 











的 作用 就 是 为 了 表示 不 在 数据 库 中 的 用 户 。 
若 想 把 角色 写 入 数据 库 ， 可 使 用 shell 会 话 : 





(venv) $ python manage.py shell 

>>> Role.insert_roles() 

>>> Role.query.all() 

[<Role u'Administrator'>, <Role u'User'>, <Role u'Moderator'>] 


9.2 赋予 角色 


用 户 在 程序 中 注册 账户 时 ， 会 被 赋予 适当 的 角色 。 大 多 数 用 户 在 注册 时 赋予 的 角色 都 是 





“用 户 ”， 因 为 这 是 默认 角色 。 唯 一 的 例外 是 管理 员 ， 管 理 员 在 最 开始 就 应 该 赋予 “管理 











匿名 ”角色 不 需要 在 数据 库 中 表示 





HH 来， 这 个 角色 





员 ” 和 角色 。 管 理 员 由 保存 在 设置 变量 FLASKY_ADMIN 中 的 电子 邮件 地 址 识别 ， 只 要 这 个 电子 
邮件 地 址 出 现在 注册 请 求 中 ， 就 会 被 赋予 正确 的 角色 。 示 例 9-4 展示 了 如 何在 User 模型 的 
构造 函数 中 完成 这 一 操作 。 








示例 9-4 app/models.py: 定义 默认 的 用 户 角 色 


class User(UserMixin, db.Model): 


# 


def _ init (self, **kwargs): 
super(User, self)._ init_ _(**kwargs) 











用 户 角 














99 


if self.role is None: 


# ... 


if self.email == current_app.config['FLASKY_ADMIN']: 

self.role = Role.query.filter_by(permissions=Qxff).first() 
if self.role is None: 

self.role = Role.query.filter_by(default=True).first() 


User 类 的 构造 函数 首先 调用 基 类 的 构造 函数 ， 如 果 创 建 基 类 对 象 后 还 没 定义 角色 ， 则 根据 
电子 邮件 地 址 决定 将 其 设 为 管理 员 还 是 默认 角色 。 


9.3 角色 验证 


为 了 简化 角色 和 权限 的 实现 过 程 ， 我 们 可 在 User 模型 中 添加 一 个 辅助 方法 ， 检 查 是 否 有 指 
定 的 权限 ， 如 示例 9-5 所 示 。 

















示例 9-5 app/models.py: 检查 用 户 是 否 有 指定 的 权限 


from flask.ext.login import UserMixin, AnonymousUserMixin 


class User(UserMixin, db.Model): 


# ... 


def can(self, permissions): 
return self.role is not None and \ 
(self.role.permissions & permissions) == permissions 


def is administrator(self): 
return self.can(Permission.ADMINISTER) 


class AnonymousUser(AnonymousUserMixin): 
def can(self, permissions): 


ret 


urn False 


def is administrator(self): 


ret 


urn False 


login_manager .anonymous_user = AnonymousUser 


User 模型 中 添加 
中 包含 请 求 的 所 
功能 经 常用 到 ， 


有 权限 位 ， 则 返回 








的 can() 方法 在 请 求 和 赋予 角色 这 两 种 权限 之 间 进 行 位 与 操作 。 如 果 角 色 


True， 表 示人 允许 用 户 执行 此 项 操作 。 检 查 管理 员 权 限 的 


因此 使 用 单独 的 方法 is_administrator() 实现 。 


出 于 一 致 性 考虑 ， 我 们 还 定义 了 AnonymousUser 类 ， 并 实现 了 can() 方法 和 is_administrator() 


方法 。 这 个 对 象 继承 





自 Flask-Login 中 的 AnonymousUserMixin 类 ， 并 将 其 设 为 用 户 未 登录 时 





current_user 的 值 。 这 样 程序 不 用 先 检查 用 户 是 否 登录 ， 就 能 自由 调用 current_user.can() 和 


Current_uUser.tis_administrator()。 





如 果 你 想 让 视图 函数 只 对 具有 特定 权限 的 用 户 开放 ， 可 以 使 用 自 定义 的 修饰 器 。 示 例 9-6 


Bley 





实现 了 两 个 修饰 器 ， 一 个 用 来 检查 常规 权限 ， 一 个 专门 用 来 检查 管理 员 权限 。 
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示例 9-6 ”app/decorators.py: 检查 用 户 权限 的 自 定 义 修 饰 器 


from functooLs import wraps 
from fLask import abort 
from fLask.ext.Login import current_user 





def permission required(permission): 
def decorator(f): 
@wraps(f) 
def decorated function(*args, **kwargs): 
if not current_user.can(permission): 
abort(403) 
return f(*args, **kwargs) 
return decorated_function 
return decorator 


def admin_required(f): 
return permission_required(Permission.ADMINISTER)(f) 


这 两 个 修饰 器 都 使 用 了 Python 标准 库 中 的 functools 包 ， 如 果 用 户 不 具有 指定 权限 ， 则 返 
回 403 错误 码 ， 即 HTTP“ 禁 止 ”错误 。 我 们 在 第 3 章 为 404 和 500 错误 编写 了 自 定义 的 
者 误 页 面 ， 所 以 现在 也 要 添加 一 个 403 错误 页 面 。 


下 面 我 们 举 两 个 例子 演示 如 何 使 用 这 些 修饰 器 




















from decorators import admin_required, permission_required 
from .models import Permission 


@main.route('/admin') 
@login_required 
@admin_required 
def for_admins_only(): 
return "For administrators!" 


@main.route('/moderator') 
@login_required 
@permission_required(Permission.MODERATE_COMMENTS) 
def for_moderators_only(): 

return "For comment moderators!" 


在 模板 中 可 能 也 需要 检查 权限 ， 所 以 Permission 类 为 所 有 位 定义 了 常量 以 便于 获取 。 为 了 
避免 每 次 调用 render_template() 时 都 多 添加 一 个 模板 参数 ， 可 以 使 用 上 下 文 处 理 器 。 上 
下 文 处 理 器 能 让 变量 在 所 有 模板 中 全 局 可 访问 。 修 改 方法 如 示例 9-7 所 示 。 











示例 9-7 app/main/_init _.py: 把 Permission 类 加 入 模板 上 下 文 


@main.app_context_processor 
def inject_ permissions(): 
return dict(Permission=Permission) 


新 添加 的 角色 和 权限 可 在 单元 测试 中 进行 测试 。 示 例 9-8 是 两 个 简单 的 测试 ， 同 时 也 演示 
了 用 法 。 
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示例 9-8 tests/test_user_model.py: 角色 和 权限 的 单元 测试 


class UserModeLTestCase(unittest.TestCase ) : 
六 


def test_roLes_and_permissions(seLf) : 
Role.insert_roles() 
U = User(email="'john@example.com', password='cat') 
self.assertTrue(uy.can(Permission.WRITE_ARTICLES)) 
self.assertFalse(y.can(Permission.MODERATE_COMMENTS)) 


def test_anonymous_user(self): 
U = AnonymousUser() 
self.assertFalse(u.can(Permission.FOLLOW)) 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
9a 签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 签 出 代码 后 记得 要 
运行 python manage.py db upgrade。 





在 你 阅读 下 一 章 之 前 ， 最 好 重新 创建 或 者 更 新 开发 数据 库 ， 如 此 一 来 ， 那 些 在 实现 角色 和 
权限 之 前 创建 的 用 户 账户 就 被 赋予 了 角色 。 





现在 ， 用 户 系统 基本 完成 了 。 在 下 一 章 ， 我 们 要 利用 这 个 系统 创建 用 户 资料 页 面 。 











第 10 章 


用 户 资 料 








在 本 章 ， 我 们 要 实现 Flasky 的 用 户 资料 页 面 。 所 有 社交 网 站 都 会 给 用 户 提供 资料 页 面 ， 其 
中 简要 显示 了 用 户 在 网 站 中 的 活动 情况 。 用 户 可 以 把 资料 页 面 的 URL 分 享 给 别人 ， 以 此 
宣告 自己 在 这 个 网 站 上 。 因 此 ， 这 个 页 面 的 URL 要 简短 易 记 。 


10.1 资料 信息 


为 了 让 用 户 的 资料 页 面 更 吸引 人 ， 我 们 可 以 在 其 中 添加 一 些 关 于 用 户 的 其 他 信息 。 示 例 
10-1 扩充 了 User 模型 ， 添 加 了 几 个 新 字段。 












































示例 10-1 app/models.py: 用 户 信息 字段 
class User(UserMixin, db.Model): 
# ... 
name = db.Column(db.String(64)) 
location = db.Column(db.String(64)) 
about me = db.Column(db.Text()) 
member_since = db.Column(db.DateTime(), default=datetime.utcnow) 
last_seen = db.Column(db.DateTime(), default=datetime.utcnow) 


新 添加 的 字段 保存 用 户 的 真实 姓名 、 所 在 地 、 自 我 介绍 、 注 册 日 期 和 最 后 访问 日 期 。about_ 
me 字段 的 类 型 是 db.Text()。db.string 和 db.Text 的 区 别 在 于 后 者 不 需要 指定 最 大 长 度 。 








两 个 时 间 惟 的 默认 值 都 是 当前 时 间 。 注 意 ，datetime.utcnow 后 面 没有 ()， 因 为 db.Column() 
的 default 参数 可 以 接受 函数 作为 默认 值 ， 所 以 每 次 需要 生成 默认 值 时 ，db.Column() 都 会 
调用 指定 的 函数 。member_since 字段 只 需要 默认 值 即 可 。 
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Last_seen 字段 创建 时 的 初始 值 也 是 当前 时 间 ， 但 用 户 每 次 访问 网 站 后 ， 这 个 值 都 会 被 刷 
新 。 我 们 可 以 在 User 模型 中 添加 一 个 方法 完成 这 个 操作 ， 如 示例 10-2 所 示 。 











示例 10-2 ”app/models.py: 刷新 用 户 的 最 后 访问 时 间 
class User(UserMixin, db.Model): 
# ... 


def ping(self): 
self.last_seen = datetime.utcnow() 
db.session.add(self) 


每 次 收 到 用 户 的 请 求 时 都 要 调用 ping() 方法 。 由 于 auth 蓝本 中 的 before_app_request 处 
理 程序 会 在 每 次 请 求 前 运行 ， 所 以 能 很 轻松 地 实现 这 个 需求 ， 如 示例 10-3 所 示 。 





示例 10-3 app/auth/views.py: 更 新 已 登录 用 户 的 访问 时 间 
Qauth.before_app_request 
def before_request() : 
if current_user.is_authenticated(): 
current_user .ping() 
if not current_user.confirmed \ 
and request.endpoint[:5] != 'auth.': 
return redirect(url_ for('auth.unconfirmed ' )) 


10.2 用户 资料 页 面 


为 每 个 用 户 都 创建 资料 页 面 并 没有 什么 难度 。 示 例 10-4 显示 了 路 由 定义 。 


























示例 10-4 app/main/views.py: 资料 页 面 的 路 由 
@main.route('/user/<username>') 
def user(username): 
user = User.query.filter_by(username=username).first() 
if user is None: 
abort(404) 
return render_template('user.html', user=user) 














这 个 路 由 在 main 蓝本 中 添加 。 对 于 名 为 john 的 用 户 ， 其 资料 页 面 的 地 址 是 http:/localhost:5000/ 
user/iohn。 这 个 视图 函数 会 在 数据 库 中 搜索 URL 中 指定 的 用 户 名 ， 如 果 找 到 ， 则 泻 染 模板 user. 
html， 并 把 用 户 名 作为 参数 传 和 模板。 如果 传 入 路 由 的 用 户 名 不 存在 ， 则 返回 404 错误 。user. 
html 模板 应 该 泻 染 保存 在 用 户 对 象 中 的 信息 。 这 个 模板 的 初始 版 本 如 示例 10-5 所 示 。 























示例 10-5 ”app/templates/user.html: 用 户 资料 页 面 的 模板 


{% block page_content %} 

<div class="page-header"> 
<h1>{{ user.username }}</h1> 
{% if user.name or user.location %} 
<p> 


{% if user.name %}{{ user.name }}{% endif %} 





{% if user.Location %} 
From <a href="http://maps.google.com/?q={{ user.Location }}"> 
{{ user.Location }} 
</a> 
{% endif %} 
</p> 
{% endif %} 
{% if current_ user.is _ administrator() %} 
<p><a href="mailto:{{ user.email }}">{{ user.email }}</a></p> 
{% endif %} 
{% if user.about me %}<p>{{ user.about me }}</p>{% endif %} 
<p> 
Member since {{ moment(user.member_since).format('L') }}. 
Last seen {{ moment(user.last_seen).fromNow() }}. 
</p> 
</div> 
{% endblock %} 


在 这 个 模板 中 ， 有 几 处 实现 细节 需要 说 明 一 下 。 
。 nane 和 1ocation 字 段 在 同一 个 <p> 元 素 中 泻 染 。 只 有 至 少 定义 了 这 两 个 字段 中 的 一 个 时 ， 
<p> 元 素 才 会 创建 。 


。 用 户 的 Location 字段 被 演 染 成 指向 谷歌 地 图 的 查询 链接 。 
。 如 果 登 录用 户 是 管理 员 ， 那 么 就 显示 用 户 的 电子 邮件 地 址 ， 且 泻 染 成 mailto 链接 。 








大 多 数 用 户 都 希望 能 很 轻松 地 访问 自己 的 资料 页 面 ， 因 此 我 们 可 以 在 导航 条 中 添加 一 个 链 
接 。 对 base.html 模板 所 做 的 修改 如 示例 10-6 所 示 。 


示例 10-6 app/templates/base.html 


{% if current_user.is authenticated() %} 
<li> 
<a href="{{ url_for('main.user', Username=current_uyser.username) }}"> 
profile 
</a> 
/Lis 
{% endif %} 


把 资料 页 面 的 链接 包含 在 条 件 语句 中 是 非常 必要 的 ， 因 为 未 认证 的 用 户 也 能 看 到 导航 条 ， 
但 我 们 不 应 该 让 他 们 看 到 资料 页 面 的 链接 。 

















10-1 展示 了 资料 页 面 在 浏览 器 中 的 样子 。 图 中 还 显示 了 刚 添加 的 资料 页 面 链 接 。 

















如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
19a 签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 一 个 数据 库 迁 移 ， 签 出 代码 后 记得 
运行 python manage.py db upgrade。 























@ee Flasky - john 
4 号 儿 合 员 土 | 人 localhost:5000 © ssadec J lO) 


john 


John Smith From Portliand, OR 
Python aficionado. 
Member since 01/05/2014. Last seen a few seconds ago. 











图 10-1 用 户 资料 页 面 


10.3 资料 编辑 器 

用 户 资料 的 编辑 分 两 种 情况 。 最 显而易见 的 情况 是 ， 用 户 要 进入 一 个 页 面 并 在 其 中 输入 自 
己 的 资料 ， 而 且 这 些 内 容 显示 在 自己 的 资料 页 面 上 。 还 有 一 种 不 大 明显 但 也 同样 重要 的 情 
况 ， 那 就 是 要 让 管理 员 能 够 编辑 任意 用 户 的 资料 不 仅 要 能 编辑 用 户 的 个 人 信息 ， 还 要 
能 编辑 用 户 不 能 直接 访问 的 User 模型 字段 ， 例 如 用 户 角色 。 这 两 种 编辑 需求 有 本 质 上 的 区 
别 ， 所 以 我 们 要 创建 两 个 不 同 的 表单 。 











x 








10.3.1 用 户 级 别 的 资料 编辑 器 


普通 用 户 的 资料 编辑 表单 如 示例 10-7 所 示 。 


示例 10-7 app/main/forms.py: 资料 编辑 表单 
class EditprofileForm(Form): 
name = StringField('Real name', validators=[Length(0, 64)]) 
location = StringField('Location', validators=[Length(0, 64)]) 
about me = TextAreaField('About me') 
submit = SubmitField('Submit') 


注意 ， 这 个 表单 中 的 所 有 字段 都 是 可 选 的 ， 因 此 长 度 验证 函数 允许 长 度 为 零 。 显 示 这 个 表 
单 的 路 由 定义 如 示例 10-8 所 示 。 


示例 10-8 app/main/views.py: 资料 编辑 路 由 
@main.route('/edit-profile', methods=['GET', 'POST']) 
@login_required 
def edit profile(): 

form = EditprofileForm() 
if form.validate on_submit(): 








current_user .name = form.name.data 
current_user.Location = form.location.data 
current_user.about me = form.about_me.data 
db.session.add(current_user) 
flash('Your profile has been updated.') 
return redirect(url_for('.user', Username=current_user .username)) 
form.name.data = current_user .name 
form.location.data = current_user.location 
form.about_ me.data = current_ user.about me 
return render_template('edit profile.html', form=form) 


在 显示 表单 之 前 ， 这 个 视图 函数 为 所 有 字段 设 定 了 初始 值 。 对 于 所 有 给 定 字段 ， 这 一 工作 
都 是 通过 把 初始 值 赋值 给 form.<field-name>.data 完成 的 。 当 form.validate_on_submit() 
返回 False 上 时， 表单 中 的 3 个 字段 都 使 用 current_user 中 保存 的 初始 值 。 提 交 表 单 后 ， 表 
单字 段 的 data 属性 中 保存 有 更 新 后 的 值 ， 因 此 可 以 将 其 赋值 给 用 户 对 象 中 的 各 字段 ， 然 后 














再 把 用 户 对 象 添加 到 数据 库 会 话 中 。 编 辑 资料 页 面 如 图 10-2 所 示 。 








为 了 让 用 户 能 轻易 找到 编辑 页 面 ， 我 们 可 以 在 资料 页 面 中 添加 一 个 链接 ， 如 示例 10-9 所 示 。 


示例 10-9 ”app/templates/user.html: 资料 编辑 的 链接 
{% if user == current_user %} 
<a class="btn btn-default" href="{{ url_for('.edit profile’') }}"> 
Edit Profile 
</a> 


{% endif %} 


链接 外 层 的 条 件 语 句 能 确保 只 有 当 用 户 查看 自己 的 资料 页 面 时 才 显 示 这 个 链接 。 





@ee Flasky ~ Edit Profile we 


Eu I] [+ localhost:5000, 










Edit Your Profile 


John Smith 


Location 


Portland, OR 


About me 


Python aficionado. 














10-2 资料 编辑 器 





10.3.2 ”管理 员 级 别 的 资料 编辑 器 

管理 员 使 用 的 资料 编辑 表单 比 普通 用 户 的 表单 更 加 复杂 。 除 了 前 面 的 3 个 资料 信息 字段 之 
外 ， 管 理 员 在 表单 中 还 要 能 编辑 用 户 的 电子 邮件 、 用 户 名 、 确 认 状 态 和 角色 。 这 个 表单 如 
示例 10-10 所 示 。 


























示例 10-10 app/main/forms.py: 管理 员 使 用 的 资料 编辑 表单 
class EditprofileAdminForm(Form): 
email = StringField('Email', validators=[Required(), Length(1, 64), 
Email()]) 
username = StringField('Username', validators=[ 
Required(), Length(1, 64), Regexp('^[A-Za-z][A-Za-z0-9_.]*$', 0, 
"Usernames must have only letters, 
"numbers，dots or underscores')]) 
confirmed = BooleanField('Confirmed') 
role = SelectField('Role', coerce=int) 
name = StringField('Real name', validators=[Length(0, 64)]) 
Location = StringField('Location', validators=[Length(0, 64)]) 
about me = TextAreaField('About me') 
submit = SubmitField('Submit') 


def _init (self, user, *args, **kwargs): 
super(EditprofileAdminForm, self). init (*args, **kwargs) 
self.role.choices = [(role.id, role.name) 
for role in Role.query.order_by(Role.name).all()] 
self.user = USser 


def validate email(self, field): 
if field.data != self.user.email and \ 
User .query.filter_by(email=field.data).first(): 
raise ValidationError('Email already registered.') 


def validate username(self, field): 
if field.data != self.user.username and \ 
User .query.filter_by(username=field.data).first(): 
raise ValidationError('Username already in use.') 


WTForms 对 HTML 表单 控件 <select> 进行 SelectField 包装 ， 从 而 实现 下 拉 列 表 ， 用 来 
在 这 个 表单 中 选择 用 户 角色 。SelectField 实例 必须 在 其 choices 属性 中 设置 各 选项 。 选 
项 必须 是 一 个 由 元 组 组 成 的 列表 ， 各 元 组 都 包含 两 个 元 素 : 选项 的 标识 符 和 显示 在 控件 中 
的 文本 字符 串 。choices 列表 在 表单 的 构造 函数 中 设 定 ， 其 值 从 Role 模型 中 获取 ， 使 用 一 
个 查询 按照 角色 名 的 字母 顺序 排列 所 有 和 角色。 元 组 中 的 标识 符 是 角色 的 id， 因 为 这 是 个 整 
数 ， 所 以 在 SelectField 构造 国 数 中 添加 coerce=int 参数 ， 从 而 把 字段 的 值 转换 为 整数 ， 
而 不 使 用 默认 的 字符 串 。 


email 和 username 字段 的 构造 方式 和 认证 表单 中 的 一 样 ， 但 处 理 验证 时 需要 更 加 小 心 。 验 
证 这 两 个 字段 时 ， 首 先 要 检查 字段 的 值 是 否 发 生 了 变化 ， 如 果 有 变化 ， 就 要 保证 新 值 不 
和 其 他 用 户 的 相应 字段 值 重复 ， 如 果 字 有 段 值 没 有 变化 ， 则 应 该 跳 过 验证 。 为 了 实现 这 个 多 















































辑 ， 表 单 构造 函数 接收 用 户 对 象 作为 参数 ， 并 将 其 保存 在 成 员 变 量 中 ， 随 后 自 定义 的 验证 





方法 要 使 用 这 个 用 户 对 象 。 


管理 员 的 资料 编辑 器 路 由 定义 如 示例 10-11 所 示 。 

















示例 10-11 app/main/views.py: 管理 员 的 资料 编辑 路 由 
@main.route('/edit-profile/<int:id>', methods=['GET', 'POST']) 
@login_required 
@admin_required 
def edit profile admin(id): 

user = User.query.get or_404(id) 
form = EditPprofileAdminForm(user=user) 
if form.validate_on_submit(): 
user.email = form.email.data 
user.username = form.username.data 
user.confirmed = form.confirmed.data 
user.role = Role.query.get(form.role.data) 
user.name = form.name.data 
User.Location = form.location.data 
user.about me = form.about_ me.data 
db.session.add(user) 
flash('The profile has been updated.') 
return redirect(url_for('.user', username=user .username)) 
form.email.data = user.email 
form.username.data = user .username 
form.confirmed.data = user.confirmed 
form.role.data = user.role id 
form.name.data = User.name 
form.Location.data = User.Location 
form.about_me.data = User.about_me 


return render_template('edit profile.html', form=form, user=user) 


这 个 路 由 和 较 简 单 的 、 普 通用 户 的 编辑 路 由 具有 基本 相同 的 结构 。 在 这 个 视图 函数 中 ， 用 
户 由 id 指定， 因此 可 使 用 Flask-SQLAlchemy 提供 的 get_or_404() 国 数 ， 如 果 提 供 的 id 























不 正确 ， 则 会 返回 404 错误 。 




















我 们 还 需要 再 探讨 一 下 用 于 选择 用 户 角 色 的 SelectField。 设 定 这 个 字段 的 初始 值 时 ， 
role_id 被 赋值 给 了 field.role.data， 这 么 做 的 原因 在 于 choices 属性 中 设置 的 元 组 列表 
使 用 数字 标识 符 表 示 各 选项 。 表 单 提交 后 ，id 从 字段 的 data 属性 中 提取 ， 并 且 查 询 时 会 
使 用 提取 出 来 的 id 值 加 载 角 色 对 象 。 表 单 中 声明 selectField 时 使 用 coerce=int 参数 ， 


























其 作用 是 保证 这 个 字段 的 data 属性 值 是 整数 。 


为 链接 到 这 个 页 面 ， 我 们 还 需 在 用 户 资 料 页 面 中 添加 一 个 链接 按钮 ， 如 示例 10-12 所 示 。 


示例 10-12 ”app/templates/user.html: 管理 员 使 用 的 资料 编辑 链接 


{% if current user.is administrator() %} 
<a class="btn btn-danger" 
href="{{ url_for('.edit profile admin', id=user.id) }}"> 
Edit Profile [Admin] 





</a> 


{% endif %} 


为 了 醒目 ， 这 个 按钮 使 用 了 不 同 的 Bootstrap 样式 进行 泻 染 。 这 里 使 用 的 条 件 语句 确保 只 当 
登录 用 户 为 管理 员 时 才 显 示 按 钮 。 











如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
19b 签 出 程序 的 这 个 版 本 。 





10.4 用 户头 像 


通过 显示 用 户 的 头像 ， 我 们 可 以 进一步 改进 资料 页 面 的 外 观 。 在 本 节 ， 你 会 学 到 如 何 添加 
Gravatar (http://gravatar.com/) 提供 的 用 户头 像 。Gravatar 是 一 个 行业 领先 的 头像 服务 ， 能 
把 头像 和 电子 邮件 地 址 关联 起 来 。 用 户 先 要 到 http://gravatar.com 中 注册 账户 ， 然 后 上 传 图 
片 。 生 成 头像 的 URL 时， 要 计算 电子 邮件 地 址 的 MDS5 散 列 值 : 























(venv) $ python 

>>> import hashlib 

>>> hashlib.md5('john@example.com' .encode('utf-8' )).hexdigest() 
'"d4c74594d841139328695756648b6bd6 


生成 的 头像 URL 是 在 http:/www.gravatar.com/avatar/ 或 https://secure.gravatar.com/avatar/ 
之 后 加 上 这 个 MD5 散 列 值 。 例 如 ， 你 在 浏览 器 的 地 址 栏 中 输入 http://www.gravatar.com/ 
avatar/d4c74594d841139328695756648b6bd6， 就 会 看 到 电子 邮件 地 址 john@example.com 对 
应 的 头像 图 片 。 如 果 这 个 电子 邮件 地 址 没有 对 应 的 头像 ， 则 会 显示 一 个 默认 图 片 。 头 像 
URL 的 查询 字符 串 中 可 以 包含 多 个 参数 以 配置 头像 图 片 的 特征 。 可 设 参数 如 表 10-1 所 示 。 






































表 10-1 _Gravatar 查 询 字 符 串 参数 



































参数 名 说 明 

s 图 片 大 小 ， 单 位 为 像素 

r 图 片 级 别 。 可 选 值 有 "g"、"pg"、"r" 和 "x* 

d ia 
认 图 片 的 URL; 图 片 生成 器 "mm"、"identicon"、"monsterid"、"wavatar"、"retro" 或 "blank" 
pe 

fd 强制 使 用 默认 头像 





我 们 可 将 构建 Gravatar URL 的 方法 添加 到 User 模型 中 ， 实 现 方式 如 示例 10-13 所 示 。 


示例 10-13 app/models.py: 生成 Gravatar URL 


import hashLib 
from fLask import request 





class User(UserMixin, db.Model): 
# ... 
def gravatar(self, size=100, default='identicon', rating='g'): 
if request.is_secure: 
url = 'https://secure.gravatar.com/avatar' 
else: 
url = 'http://www.gravatar .com/avatar' 
hash = hashlib.md5(self.email.encode('utf-8')).hexdigest() 
return '{url}/{hash}?s={size}&d={default}&r={rating}' .format( 
url=url, hash=hash, size=size, default=default, rating=rating) 


这 一 实现 会 选择 标准 的 或 加 密 的 Gravatar URL 基 以 匹配 用 户 的 安全 需求 。 头 像 的 URL 由 
URL 基 、 用 户 电子 邮件 地 址 的 MD5 散 列 值 和 参数 组 成 ， 而 且 各 参数 都 设 定 了 默认 值 。 有 
了 上 述 实现 ， 我 们 就 可 以 在 Python shell 中 轻易 生成 头像 的 URL 了 : 








(venv) $ python manage.py shell 

>>> U = User(email='john@example.com') 

>>> U.gravatar() 

'http://www.gravatar .com/avatar/d4c74594d84113932869575bd6?s=100&d=identicon&r=g' 
>>> U.gravatar(size=256) 

'http://www.gravatar .com/avatar/d4c74594d84113932869575bd6?s=256&d=identicon&r=g' 





gravatar() 方法 也 可 在 Jinja2 模板 中 调用 。 示 例 10-14 在 资料 页 面 中 添加 了 一 个 大 小 为 
256 像素 的 头像 。 


示例 10-14 ”app/tempaltes/user.html: 资料 页 面 中 的 头像 

mg class="img-rounded profile-thumbnail" src="{{ user.gravatar(size=256) }}"> 
使 用 类 似 方 式 ， 我 们 可 在 基 模 板 的 导航 条 上 添加 一 个 已 登录 用 户头 像 的 小 型 缩 略 图 。 为 了 
更 好 地 调整 页 面 中 头像 图 片 的 显示 格式 ， 我 们 可 使 用 一 些 自 定义 的 CSS 类。 你 可 以 在 源码 


仓库 的 styles.css 文件 中 查看 自 定义 的 CSS，styles.css 文件 保存 在 程序 静态 文件 的 文件 夹 
中 ， 而 且 要 在 base.html 模板 中 引用 。 图 10-3 为 显示 了 头像 的 用 户 资料 页 面 。 



































如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
16c 签 出 程序 的 这 个 版 本 。 











生成 头像 时 要 生成 MD5 值 ， 这 是 一 项 CPU 密集 型 操作 。 如 果 要 在 某 个 页 面 中 生成 大 量 头 
像 ， 计 算 量 会 非常 大 。 由 于 用 户 电子 邮件 地 址 的 MD5 散 列 值 是 不 变 的 ， 因 此 可 以 将 其 组 
存在 User 模型 中 。 若 要 把 MD5 散 列 值 保 存在 数据 库 中 ， 需 要 对 User 模型 做 些 改动 ， 如 示 
例 10-15 所 示 。 























eee Flasky ~ john Me 


| 上 [S) | + Cocanosesooo 


John Smith 

From Portland, OR 

Python aficionado. 

Member since 01/05/2014. Last seen a few seconds ago. 


Edit Profile 


eh 





10-3 ”显示 了 头像 的 用 户 资料 页 面 


示例 10-15 


app/models.py: 使 用 缓存 的 MD5 散 列 值 生 成 Gravatar URL 


class User(UserMixin, db.Model): 
类 
avatar_hash = db.Column(db.String(32)) 


def 


def 


def 


__init_ (self, **kwargs): 
# ... 
if self.email is not None and self.avatar_hash is None: 
self.avatar_hash = hashLib.md5( 
self.email.encode('utf-8')).hexdigest() 


change_email(self, token): 

# ... 

self.email = new_email 

self.avatar_hash = hashLib.md5( 
self.email.encode('utf-8')).hexdigest() 

db.session.add(self) 

return True 


gravatar(self, size=100, default='identicon', rating='g'): 

if request.is_ secure: 
url = 'https://secure.gravatar .com/avatar' 

else: 
url = 'http://www.gravatar .com/avatar' 

hash = seLf.avatar_hash or hashLib.md5( 
self.email.encode('utf-8')).hexdigest() 

return '{url}/{hash}?s={size}8&d={default}&r={rating}'.format( 
url=url, hash=hash, size=size, default=default, rating=rating) 








模型 初始 化 过 程 中 会 计算 电子 邮件 的 散 列 值 ， 然 后 存 入 数据库 ， 若 用 户 更 新 了 电子 邮件 
地 址 ， 则 会 重新 计算 散 列 值 。gravatar() 方法 会 使 用 模型 中 保存 的 散 列 值 ， 如 果 模 型 中 没 
有 ， 就 和 之 前 一 样 计算 电子 邮件 地 址 的 散 列 值 。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
10d 签 出 程序 的 这 个 版 本 。 这 个 版 本 中 包含 了 一 个 数据 库 迁移 ， 签 出 代码 后 
记得 要 运行 python manage.py db upgrade。 











下 一 章 ， 我 们 会 创建 这 个 程序 使 用 的 博客 引擎 。 











在 本 章 ， 我 们 要 实现 Flasky 的 主要 功能 ， 即 允许 用 户 阅 读 、 撰 写 博客 文章 。 本 章 你 会 学 到 
一 些 新 技术 : 重用 模板 、 分 页 显示 长 列表 以 及 处 理 富 文本 。 


11.1 提交 和 显示 博客 文章 


为 支持 博客 文章 ， 我 们 需要 创建 一 个 新 的 数据 库 模型 ， 如 示例 11-1 所 示 。 





示例 11-1 app/models.py: 文章 模型 
class Post(db.Model): 
_ tabLename_ = 'posts' 
id = db.Column(db.Integer, primary_key=True) 
body = db.Column(db.Text) 
timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow) 
author_id = db.Column(db.Integer, db.ForeignKey('users.id')) 


class User(UserMixin, db.Model): 
# ... 
posts = db.relationship('Post', backref='author', lazy='dynamic') 


博客 文章 包含 正文 、 时 间 改 以 及 和 User 模型 之 间 的 一 对 多 关系 。body 字段 的 定义 类 型 是 
db.Text， 所 以 不 限制 长 度 。 

在 程序 的 首页 要 显示 一 个 表单 ， 以 便 让 用 户 写 博客 。 这 个 表单 很 简单 ， 只 包括 一 个 多 行文 本 
输入 框 ， 用 于 输入 博客 文章 的 内 容 ， 另 外 还 有 一 个 提交 按钮 ， 表 单 定义 如 示例 11-2 所 示 。 








示例 11-2 ”app/main/forms.py: 博客 文章 表单 


class PostForm(Form) : 
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body = TextAreaField("What's on your mind?", validators=[Required()]) 


submit = SubmitField('Submit') 








index() 视图 函数 处 理 这 个 表单 并 把 以 前 发 布 的 博客 文章 列表 传 给 模板 ， 如 示例 11-3 所 示 。 














示例 11-3 ”app/main/views.py: 处 理 博客 文章 的 首页 路 由 
@main.route('/', methods=['GET', 'POST']) 
def index(): 
form = PostForm() 
if current_user.can(Permission.WRITE ARTICLES) and \ 
form.validate_on_submit(): 
post = Post(body=form.body .data， 
author=current_uUser._ get_current_object()) 
db.session.add(post) 
return redirect(url_for('.index')) 
posts = Post.query.order_by(Post.timestamp.desc()).all() 
return render_template('index.html', form=form, posts=posts) 





这 个 视图 函数 把 表单 和 完整 的 博客 文章 列表 传 给 模板 。 文 章 列表 按照 时 间 惟 进 行 降序 排 
列 。 博 客 文章 表单 采取 惯常 处 理 方式 ， 如 果 提 交 的 数据 能 通过 验证 就 创建 一 个 新 Post 实 

















例 。 在 发 布 新 文章 之 前 ， 要 检查 当前 用 户 是 否 有 写 文章 的 权限 。 





注意 ， 新 文章 对 象 的 author 属性 值 为 表达 式 current_user._get_current_object()。 变 量 
current_user 由 Flask-Login 提供 ， 和 所 有 上 下 文 变量 一 样 ， 也 是 通过 线程 内 的 代理 对 象 实 
现 。 这 个 对 象 的 表现 类 似 用 户 对 象 ， 但 实际 上 却 是 一 个 轻 度 包装 ， 包 含 真正 的 用 户 对 象 。 





数据 库 需要 真正 的 用 户 对 象 ， 因 此 要 调用 _get_current_object() 方法 。 





这 个 表单 显示 在 index.html 模板 中 欢迎 消息 的 下 方 ， 其 后 是 博客 文章 列表 。 
章 列表 中 ， 我 们 首次 尝试 创建 博客 文章 时 间 轴 ， 按 照 时 间 顺 序 由 新 到 旧 列 日 
有 的 博客 文章 。 对 模板 所 做 的 改动 如 示例 11-4 所 示 。 








示例 11-4 _ app/templates/index.html: 显示 博客 文章 的 首页 模板 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 





<div> 
{% if current_user.can(Permission.WRITE_ARTICLES) %} 
{{ wtf.quick_form(form) }} 
{% endif %} 
</div> 
<ul class="posts"> 
{% for post in posts %} 
<li class="post"> 
<div class="profile-thumbnail"> 


在 这 个 博客 文 
H 了 数据 库 中 所 


<a href="{{ url_for('.user', username=post.author.username) }}"> 


<img class="img-rounded profile-thumbnail" 
src="{{ post.author .gravatar(size=40) }}"> 
</a> 
</div> 





116 | 第 11 章 


<div class="post-date">{{ moment(post.timestamp).fromNow() }}</div> 
<div class="post-author"> 
<a href="{{ url_for('.user', username=post.author.username) }}"> 
{{ post.author.username }} 
</a> 
</div> 
<div class="post-body">{{ post.body }}</div> 
</li> 
{% endfor %} 
</ul> 


注意 ， 如 果 用 户 所 属 角 色 没 有 WRITE_ARTICLES 权限 ， 则 经 User .can() 方法 检查 后 ， 不 会 显 
示 博 客 文章 表单 。 博 客 文章 列表 通过 HTML 无 序列 表 实 现 ， 并 指定 了 一 个 CSS 类 ， 从 而 
让 格式 更 精美 。 页 面 左 侧 会 显示 作者 的 小 头像 ， 头 像 和 作者 用 户 名 都 泻 染 成 链接 形式 ， 可 
链接 到 用 户 资 料 页 面 。 所 用 的 CSS 样式 都 存储 在 程序 static 文件 夹 里 的 style.css 文件 中 。 
你 可 到 GitHub 仓库 中 查看 这 个 文件 。 显 示 有 表单 和 博客 文章 列表 的 首页 如 图 11-1 所 示 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 11a 
签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 了 一 个 数据 库 迁 移 ， 签 出 代码 后 记得 要 
运行 python manage.py db upgrade。 




















Hello, johnl! 


What's on your mind? 


2 days ago 
1 Integer pede justo, lacinia eget, tincidunt eget, tempus vel, pede. 


FE 2 days ago 
Pi Nulla ac enim. Nulla ut erat id mauris vulputate elementum. In tempor turpis nec euismod scelerisque, 
quam turpis adipiscing lorem, vitae mattis nibh ligula nec sem. Nunc nisl. Nullam varius. 


| marilyn89 2 days ago 
Aenean sit amet justo. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia 
Curae; Mauris viverra diam vitae quam. Fusce posuere felis sed lacus. 


SE cherylo0 2 days ago 














图 11-1 显示 有 博客 发 布 表单 和 博客 文章 列表 的 首页 
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~ rw Tm Pe 
11.2 ”在 资料 页 中 显示 博客 文章 
我 们 可 以 将 用 户 资料 页 改进 一 下 ， 在 上 面 显示 该 用 户 发 布 的 博客 文章 列表 。 示 例 11-5 是 对 
视图 函数 所 做 的 改动 ， 用 以 获取 文章 列表 。 























示例 11-5 ”app/main/views.py: 获取 博客 文章 的 资料 页 路 由 


@main.route('/user/<username>') 
def user(username): 
user = User.query.filter_by(username=username).first() 
if user is None: 
abort(404) 
posts = user.posts.order_by(Post.timestamp.desc()).all() 
return render_template('user.html', user=user, posts=posts) 








用 户 发 布 的 博客 文章 列表 通过 User .posts 关系 获取 ，User .posts 返回 的 是 查询 对 象 ， 因 此 
可 在 其 上 调用 过 滤器 ， 例 如 order_by()。 





和 index.html 模板 一 样 ，user.html 模板 也 要 使 用 一 个 HTML <ul> 元 素 浑 染 博客 文章 。 维 护 
两 个 完全 相同 的 HTML 片段 副本 可 不 是 个 好 主意 ， 遇 到 这 种 情况 ，Jinja2 提供 的 tnctude() 
指令 就 非常 有 用 。userhtml 模板 包含 了 其 他 文件 中 定义 的 列表 ， 如 示例 11.6 所 示 。 


示例 11-6 ”app/templates/user.html: 显示 有 博客 文章 的 资料 页 模板 


<h3>Posts by {{ user.username }}</h3> 
{% include '_posts.html' %} 


为 了 完成 这 种 新 的 模板 组 织 方 式 ，index.html 模板 中 的 <ul> 元 素 需 要 移 到 新 模板 _posts. 
html 中 ， 并 替换 成 另 一 个 include() 指令 。 注 意 ，_posts.html 模板 名 的 下 划 线 前 级 不 是 必 
须 使 用 的 ， 这 只 是 一 种 习惯 用 法 ， 以 区 分 独立 模板 和 局 部 模板 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 9it checkout 
11b 签 出 程序 的 这 个 版 本 。 








11.3 分 页 显示 长 博客 文章 列表 


随 着 网 站 的 发 展 ， 博 客 文章 的 数量 会 不 断 增 多 ， 如 果 要 在 首页 和 资料 页 显示 全 部 文章 ， 浏 
览 速度 会 变 慢 且 不 符合 实际 需求 。 在 Web 浏览 器 中 ， 内 容 多 的 网 页 需要 花费 更 多 的 时 间 生 
成 、 下 载 和 谊 染 ， 所 以 网 页 内 容 变 多 会 降低 用 户 体验 的 质量 。 这 一 问题 的 解决 方法 是 分 页 
显示 数据 ， 进 行 片段 式 泻 染 。 
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11.3.1 创建 虚拟 博客 文章 数据 

若 想 实现 博客 文章 分 页 ， 我 们 需要 一 个 包含 大 量 数据 的 测试 数据 库 。 手 动 添加 数据 库 记 录 
浪费 时 间 而 且 很 麻烦 ， 所 以 最 好 能 使 用 自动 化 方案 。 有 多 个 Python 包 可 用 于 生成 虚拟 信 
息 ， 其 中 功能 相对 完善 的 是 ForgeryPy， 可 以 使 用 pip 进行 安装 : 

















(venv) $ pip install forgerypy 


严格 来 说 ，ForgeryPy 并 不 是 这 个 程序 的 依赖 ， 因 为 它 只 在 开发 过 程 中 使 用 。 为 了 区 分 生 
产 环 境 的 依赖 和 开发 环境 的 依赖 ， 我 们 可 以 把 文件 requirements.txt 换 成 requirements 文件 
夹 ， 它 们 分 别 保存 不 同 环境 中 的 依赖 。 在 这 个 新 建 的 文件 夹 中 ， 我 们 可 以 创建 一 个 dev.txt 
文件 ， 列 出 开发 过 程 中 所 需 的 依赖 ， 再 创建 一 个 prod.txt 文件 ， 列 出 生产 环境 所 需 的 依赖 。 
由 于 两 个 环境 所 需 的 依赖 大 部 分 是 相同 的 ， 因 此 可 以 创建 一 个 common.txt 文件 ， 在 dev.txt 
和 prod.txt 中 使 用 -r 参数 导入 。dev.txt 文件 的 内 容 如 示例 11-7 所 示 。 














示例 11-7 requirements/dev.txt: 开发 所 需 的 依赖 文件 


-Tr Common .七 Xt 
ForgeryPy==0.1 


示例 11-8 展示 了 添加 到 User 模型 和 Post 模型 中 的 类 方法 ， 用 来 生成 虚拟 数据 。 
示例 11-8 app/models.py: 生成 虚拟 用 户 和 博客 文章 


class User(UserMixin, db.Model): 
# ... 
@staticmethod 
def generate_fake(count=100): 
from sqlalchemy.exc import IntegrityError 
from random import seed 
import forgery_py 


seed() 
for i in range(count): 

U = User(email=forgery_py.internet.email_address(), 
username=forgery_py.internet.user_name(True), 
password=forgery_py. lorem ipsum.word(), 
confirmed=True, 
name=forgery_py.name.full_name(), 
location=forgery_py.address.city(), 
about_me=forgery_py.lorem ipsum.sentence(), 
member_since=forgery_py.date.date(True)) 

db.session.add(u) 

try: 

db.session.commit() 
except IntegrityError: 
db.session.rollback() 


class Post(db.Model): 
# ... 
@staticmethod 
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def generate_fake(count=100): 
from random import seed, randint 
import forgery_py 


seed() 
User_count = User.query.count() 
for i in range(count): 
U = User.query.offset(randint(0, user_count - 1)).first() 
p = Post(body=forgery_py.lorem ipsum.sentences(randint(1, 3)), 
timestamp=forgery_py.date.date(True), 
author=u) 
db.session.add(p) 
db.session.commit() 














这 些 虚 拟 对 象 的 属性 由 ForgeryPy 的 随机 信息 生成 器 生成 ， 其 中 的 名 字 、 电 子 邮 件 地 址 、 
句子 等 属性 看 起 来 就 像 真 的 一 样 。 


用 户 的 电子 邮件 地 址 和 用 户 名 必须 是 唯一 的 ， ee em 因 
此 有 重复 的 风险 。 如 果 发 生 了 这 种 不 太 可 能 出 现 的 情况 ， 提 交 数 据 库 会 话 时 会 抛 出 
IntegrityError 异常 。 这 个 异常 的 处 理 方式 是 ， 在 继 纪 ee， 在 循环 中 生成 
重复 内 容 时 不 会 把 用 户 写 人 数据库， 因此 生成 的 虚拟 用 户 总 数 可 能 会 比 预 期 少 。 
































随机 生成 文章 时 要 为 每 篇 文章 随机 指定 一 个 用 户 。 为 此 ， 我 们 使 用 offset() 查询 过 滤器 。 
这 个 过 滤器 会 跳 过 参数 中 指定 的 记录 数量 。 通 过 设 定 一 个 随机 的 偏 移 值 ， 再 调用 first() 
方法 ， 就 能 每 次 都 获得 一 个 不 同 的 随机 用 户 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11c 签 出 程序 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 我 们 还 要 运行 pip 


install -r requirements/dev.txt, 














使 用 新 添加 的 方法 ， 我 们 可 以 在 Python shell 中 轻易 生成 大 量 虚 拟 用 户 和 文章 : 








(venv) $ python manage.py shell 
>>> User .generate fake(100) 
>>> Post.generate fake(100) 





如 果 你 现在 运行 程序 ， 会 看 到 首页 中 显示 了 一 个 很 长 的 随机 博客 文章 列表 。 


11.3.2 ”在 页 面 中 泻 染 数据 


示例 11-9 展示 了 为 支持 分 页 对 首页 路 由 所 做 的 改动 。 





示例 11-9 ”app/main/views.py: 分 页 显示 博客 文章 列表 
@main.route('/', methods=['GET', 'POST']) 





120 | 第 11 章 


def index(): 

# ... 

page = request.args.get('page', 1, type=int) 

pagination = Post.query.order_by(Post.timestamp.desc()).paginate( 
page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'], 
error_out=False) 

posts = pagination.items 

return render_template('index.html', form=form, posts=posts, 

pagination=pagination) 


泻 染 的 页 数 从 请 求 的 查询 字符 串 (request.args) 中 获取 ， 如 果 没 有 明确 指定 ， 则 默认 演 
染 第 一 页 。 参数 type=int 保证 参数 无 法 转换 成 整数 时 ， 返 回 默认 值 。 














为 了 显示 某 页 中 的 记录 ， 要 把 aLL() 换 成 Flask-SQLAlchemy 提供 的 paginate() 方法。 页 
数 是 paginate() 方法 的 第 一 个 参数 ， 也 是 唯一 必需 的 参数 。 可 选 参数 per_page 用 来 指定 
每 页 显示 的 记录 数量 ， 如 果 没 有 指定 ， 则 默认 显示 20 个 记录 。 另 一 个 可 选 参数 为 error_ 








out， 当 其 设 为 True 时 (默认 值 )， 


如 果 请 求 的 页 数 超出 了 范围 ， 则 会 返回 404 错误 ， 如 有 果 


设 为 False， 页 数 超出 范围 时 会 返 
数量 ， 参 数 per_page 的 值 从 程序 的 环境 








回 一 个 空 列 表 。 为 了 能 够 很 便利 地 配置 每 页 显示 的 记录 


变量 FLASKY_POSTS_PER_PAGE 中 读 取 。 





这 样 修改 之 后 ， 首 页 中 的 文章 列表 只 


要 在 浏览 器 


11.3.3 


会 显示 有 限 数量 的 文章 。 若 想 查看 第 2 页 中 的 文章 ， 


地 址 栏 中 的 URL 后 加 上 查询 字符 串 ?page=2。 


添加 分 页 导航 


paginate() 方法 的 返 下 





回 值 是 一 个 Pagination 类 对 象 ， 


这 个 类 在 Flask-SQLAlchemy 中 定义 。 








这 个 对 象 包含 很 多 属性 ， 用 于 在 模板 中 生成 分 页 链接 ， 因 此 将 其 作为 参数 传 入 了 模板 。 分 
页 对 象 的 属性 简介 如 表 11-1 所 示 。 












































表 11-1 Flask-SQLAIchemy 分 页 对 象 的 属性 
属 性 说 明 

items 当前 页 面 中 的 记录 

query 分 页 的 源 查 询 

page 当前 页 数 

prev_num 上 一 页 的 页 数 

next_num 下 一 页 的 页 数 

has_next 如 果 有 下 一 页 ， 返 回 True 

has_prev 如 果 有 上 一 页 ， 返 回 True 

pages 查询 得 到 的 总 页 数 

per_page 每 页 显示 的 记录 数量 

total 查询 返回 的 记录 总 数 

在 分 页 对 象 上 还 可 调用 一 些 方法 ， 如 表 11-2 所 示 。 
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表 11-2 ”在 Flask-SQLAIchemy 对 象 上 可 调用 的 方法 

疗 族 说 明 

iter_pages 一 个 迭代 器 ， 返 回 一 个 在 分 页 导航 中 显示 的 页 数列 表 。 这 个 列表 的 最 左边 显示 left_ 
(Left_edge=2，edge 页 ， 当 前 页 的 左边 显示 Left_current 页 ， 当 前 页 的 右边 显示 right_current 页 ， 
left_current=2， 最 右边 显示 right_edge 页 。 例 如 ， 在 一 个 100 页 的 列表 中 ， 当 前 页 为 第 50 页， 使 用 
right_current=5， 上 默认 配置 ， 这 个 方法 会 返回 以 下 页 数 : 1、2、None、48、49、50、51、52、53、54、 























right_edge=2) 55、None、99、100。None 表示 页 数 之 间 的 间隔 
prev() 上 一 页 的 分 页 对 象 
next() 下 一 页 的 分 页 对 象 





拥有 这 么 强大 的 对 象 和 Bootstrap 中 的 分 页 CSS 类 ， 我 们 很 轻易 地 就 能 在 模板 底部 构建 一 
个 分 页 导航 。 示 例 11-10 是 以 Jinja2 宏 的 形式 实现 的 分 页 导航 。 





示例 11-10 ”app/templates/_macros.html: 分 页 模板 宏 


{% macro pagination widget(pagination, endpoint) %} 
<ul class="pagination"> 
<li{% if not pagination.has_prev %} class="disabled"{% endif %}> 
<a href="{% if pagination.has_prev %}{{ url_for(endpoint, 
page = pagination.page - 1, **kwargs) }}{% else %}#{% endif %}"> 
&laquo; 
</a> 
</li> 
{% for p in pagination.iter_pages() %} 
{% if p %} 
{% if p == pagination.page %} 
<li class="active"> 
<a href="{{ url_for(endpoint, page = p, **kwargs) }}">{{ p }}</a> 


</li> 
{% else %} 
<li> 
<a href="{{ url_for(endpoint, page = p, **kwargs) }}">{{ p }}</a> 
</li> 


{% endif %} 
{% else %} 
<li class="disabled"><a href="#">&hellip;</a></li> 
{% endif %} 
{% endfor %} 
<li{% if not pagination.has_next %} class="disabled"{% endif %}> 
<a href="{% if pagination.has_next %}{{ url_for(endpoint, 
page = pagination.page + 1, **kwargs) }}{% else %}#{% endif %}"> 
&raquo; 
</a> 
< /LiL> 
</ul> 
{% endmacro %} 











这 个 宏 创 建 了 一 个 Bootstrap 分 页 元 素 ， 即 一 个 有 特殊 样式 的 无 序列 表 ， 其 中 定义 了 下 述 页 
昌 链接。 


。“ 上 一 页 ”链接 。 如 有 果 当 前 页 是 第 一 页 ， 则 为 这 个 链接 加 上 disabled 类 。 























。 分 页 对 象 的 iter_pages() 迭代 器 返回 的 所 有 页 面 链 接 。 这 些 页 面 被 演 染 成 具有 明确 页 
数 的 链接 ， 页 数 在 url_for() 的 参数 中 指定 。 当 前 显示 的 页 面 使 用 activeCSS 类 高 亮 显 
示 。 页 数列 表 中 的 间隔 使 用 省 略 号 表示 。 

。“ 下 一 页 ”链接 。 如 果 当 前 页 是 最 后 一 页 ， 则 会 禁用 这 个 链接 。 


Jinja2 宏 的 参数 列表 中 不 用 加 入 **kwargs 即 可 接收 关键 字 参 数 。 分 页 宏 把 接收 到 的 所 有 关 
键 字 参 数 都 传 给 了 生成 分 页 链接 的 urt_for() 方法 。 这 种 方式 也 可 在 路 由 中 使 用 ， 例 如 包 
含 一 个 动态 部 分 的 资料 页 。 


pagination_widget 宏 可 放 在 index.html 和 user.html 中 的 _posts.html 模板 后 面 。 示 例 11-11 
是 它 在 程序 首页 中 的 应 用 。 


示例 11-11 app/templates/index.html: 在 博客 文章 列表 下 面 添加 分 页 导航 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 
{% import "_macros.html" as macros %} 


{% include '_posts.html' %} 
<div class="pagination"> 
{{ macros.pagination widget(pagination, '.index') }} 
</div> 
{% endif %} 


页 面 中 的 分 页 链接 如 图 11-2 所 示 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11d 签 出 程序 的 这 个 版 本 。 











velit 
Fusce lacus purus, aliquet at, feugiat non, pretium quis, lectus. Praesent blandit lacinia erat. Nullam orci 
pede, venenatis non, sodales sed, tincidunt eu, felis. 


”ee maria71 13 days ago 


> Nullam varius. 














11-2 ”博客 文章 分 页 链接 
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11.4 使 用 Markdown 和 Flask-PageDown 支 持 富 
文本 文章 


对 于 发 布 短 销 息 和 状态 更 新 来 说 ， 纯 文本 足够 用 了 ， 但 如 果 用 户 想 发 布 长 文章 ， 就 会 觉得 
在 格式 上 受到 了 限制 。 本 节 我 们 要 将 输入 文章 的 多 行文 本 输入 框 升级 ， 让 其 支持 Markdown 
(http://daringfireball.net/projects/markdown/) 语法 ， 还 要 添加 富 文本 文章 的 预览 功能 。 


实现 这 个 功能 要 用 到 一 些 新 包 。 


。 PageDown: 使 用 JavaScript 实现 的 客户 端 Markdown 到 HTML 的 转换 程序 。 

。 Flask-PageDown: 为 Flask 包装 的 PageDown， 把 PageDown 集成 到 Flask-WTF 表单 中 。 
。 Markdown: 使 用 Python 实现 的 服务 器 端 Markdown 到 HTML 的 转换 程序 。 

。 Bleach: 使 用 Python 实现 的 HTML 请 理 器 。 




















这 些 Python 包 可 使 用 pip 安装 : 


(venv) $ pip install fLask-pagedown markdown bleach 


11.4.1 使 用 Flask-PageDown 


Flask-PageDown 扩展 定义 了 一 个 PageDownField 类 ,这 个 类 和 WTForms 中 的 TextAreaField 
接口 一 致 。 使 用 PageDownField 字段 之 前 ， 先 要 初始 化 扩展 ， 如 示例 11-12 所 示 。 


示例 11-12 ”app/_init _.py: 初始 化 Flask-PageDown 
from fLask.ext.pagedown import PageDown 
ee = PageDown() 
ee 
ee 
Hs 


若 想 把 首页 中 的 多 行文 本 控件 转换 成 Markdown 富 文 本 编辑 器 ，PostForm 表单 中 的 body 字 
段 要 进行 修改 ， 如 示例 11-13 所 示 。 


示例 11-13 app/main/forms.py: 启用 Markdown 的 文章 表单 
from flask.ext.pagedown.fields import PageDownField 
class PostForm(Form) : 


body = PageDownField("What's on your mind?", validators=[Required()]) 
submit = SubmitField('Submit') 


Markdown 预览 使 用 PageDown 库 生 成 ， 因 此 要 在 模板 中 修改 。Flask-PageDown 简化 了 这 





个 过 程 ， 提 供 了 一 个 模板 宏 ， 从 CDN 中 加 载 所 需 文 件 ， 如 示例 11-14 所 示 。 


示例 11-14 app/index.html: Flask-PageDown 模板 声明 


{% block scripts %} 

{{ super() }} 

{{ pagedown.include_pagedown() }} 
{% endblock %} 


如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
1le 签 出 程序 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 请 执行 pip install -r 


requirements/dev.txt, 


做 了 上 述 修 改 后， 在 多 行文 本 字段 中 输入 Markdown 格式 的 文本 会 被 立即 渲染 成 HTML 并 
显示 在 输入 框 下 方 。 富 文本 博客 文章 表单 如 图 11-3 所 示 。 








eee a 和 
—— ~ 





Hello, john! 


What's on your mind? 


# This is a top-level heading 
This is a regular paragraptl 





This is a top-level heading 
This is a regular paragraph 














图 11-3 ”语文 本 博客 文章 表单 


11.4.2 ”在 服务 器 上 处 理 富 文本 

提交 表单 后 ，P0ST 请 求 只 会 发 送 纯 Markdown 文本 ， 页 面 中 显示 的 HTML 预览 会 被 丢掉 。 
和 表单 一 起 发 送 生 成 的 HTML 预览 有 安全 隐患 ， 因 为 攻击 者 轻易 就 能 修改 HTML 代码 ， 
让 其 和 Markdown 源 不 匹配 ， 然 后 再 提交 表单 。 安 全 起 见 ， 只 提交 Markdown 源 文本 ， 在 
服务 器 上 使 用 Markdown (使 用 Python 编写 的 Markdown 到 HTML 转换 程序 ) 将 其 转换 
成 HTML。 得 到 HTML 后 ， 再 使 用 Bleach 进行 清理 ， 确 保 其 中 只 包含 几 个 允许 使 用 的 
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HTML 标签 。 


把 Markdown 格式 的 博客 文章 转换 成 HTML 的 过 程 可 以 在 _posts.html 模板 中 完成 ， 但 这 
么 做 效率 不 高 ， 因 为 每 次 这 染 页 面 时 都 要 转换 一 次 。 为 了 避免 重复 工作 ， 我 们 可 在 创建 博 
客 文章 时 做 一 次 性 转换 。 转 换 后 的 博客 文章 HTML 代码 缓存 在 Post 模型 的 一 个 新 字段 中 ， 
在 模板 中 可 以 直接 调用 。 文 章 的 Markdown 源 文 本 还 要 保存 在 数据 库 中 ， 以 防 需 要 编辑 。 
示例 11-15 是 对 Post 模型 所 做 的 改动 。 











示例 11-15 ”app/models.py: 在 Post 模型 中 处 理 Markdown 文本 


from markdown import markdown 
import bleach 








class Post(db.Model): 
# ... 
body_html = db.Column(db.Text) 


# ... 
@staticmethod 
def on_changed_body(target, value, oldvalue, initiator): 
allowed tags = ['a', 'abbr', 'acronym', 'b', 'blockquote', 'code', 
em Ts "Ls “ol, "pre, strong's "UL", 
"hi Mh2";, “ha, "EJ 
target.body_html = bleach.linkify(bleach.clean( 
markdown(value, output_ format='html'), 
tags=allowed_tags, strip=True)) 


db.event.listen(Post.body, 'set', Post.on_changed_body) 





on_changed_body 函数 注册 在 body 字段 上 ， 是 SQLAlchemy “set” 事 件 的 监听 程序 ， 这 意 
味 着 只 要 这 个 类 实例 的 body 字段 设 了 新 值 ， 函 数 就 会 自动 被 调用 。on_changed_body 函数 
把 body 字段 中 的 文本 泻 染 成 HTML 格式， 结果 保存 在 body_html 中 ， 自 动 且 高 效 地 完成 
Markdown 文本 到 HTML 的 转换 。 














真正 的 转换 过 程 分 三 步 完 成 。 首 先 ，markdown() 函数 初步 把 Markdown 文本 转换 成 HIML。 
然后 ， 把 得 到 的 结果 和 人 允许 使 用 的 HTML 标签 列表 传 给 clean() 函数 。clean() 函数 删除 
所 有 不 在 白 名 单 中 的 标签 。 转 换 的 最 后 一 步 由 tinkify() 函数 完成 ， 这 个 函数 由 Bleach 提 
供 ， 把 纯 文本 中 的 URL 转换 成 适当 的 <a> 链接 。 最 后 一 步 是 很 有 必要 的 ， 因 为 Markdown 
规范 没有 为 自动 生成 链接 提供 官方 支持 。PageDown 以 扩展 的 形式 实现 了 这 个 功能 ， 因 此 
在 服务 器 上 要 调用 Linkify() 函数 。 















































最 后 ， 如 果 post.body_html 字段 存在 ， 还 要 把 post.body 换 成 post.body_htmL， 如 示例 
11-16 所 示 。 


示例 11-16 ”app/templates/_posts.html: 在 模板 中 使 用 文章 内 容 的 HTML 格式 


<div class="post-body"> 
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{% if post.body_htmL %} 
{{ post.body_htmL | safe }} 
{% else %} 
{{ post.body }} 
{% endif %} 
</div> 


演 染 HTML 格式 内 容 时 使 用 | safe 后 级 ， 其 目的 是 告诉 Jinja2 不 要 转 义 HTML 元 素 。 出 
于 安全 考虑 ， 默 认 情况 下 Jinja2 会 转 义 所 有 模板 变量 。Markdown 转换 成 的 HTML 在 服务 
器 上 生成 ， 因 此 可 以 放心 浑 染 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
11f 签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 了 一 个 数据 库 迁 移 ， 签 出 代码 后 记 
得 要 运行 python manage.py db upgrade。 为 保证 你 安装 了 所 有 依赖 ， 还 要 执 
行 pip install -r requirements/dev.txt, 











11.5 博客 文章 的 固定 链接 


用 户 有 时 希望 能 在 社交 网 络 中 和 朋友 分 享 某 篇 博客 文章 的 链接 。 为 此 ， 每 篇 文章 都 要 有 一 
个 专 页 ， 使 用 唯一 的 URL 引用 。 支 持 固 定 链接 功能 的 路 由 和 视图 函数 如 示例 11-17 所 示 。 























示例 11-17 app/main/views.py: 文章 的 固定 链接 
@main.route('/post/<int:id>') 
def post(id): 
post = Post.query.get or_404(id) 
return render_template('post.html', posts=[post]) 


博客 文章 的 URL 使 用 插入 数据 库 时 分 配 的 唯一 id 字段 构建 。 





某 些 类 型 的 程序 使 用 可 读 性 高 的 字符 串 而 不 是 数字 ID 构建 固定 链接 。 除 了 
数字 ID 之 外 ， 程 序 还 为 博客 文章 起 了 个 独特 的 字符 串 别 名 。 











注意 ，posthtml 模板 接收 一 个 列表 作为 参数 ， 这 个 列表 就 是 要 泻 染 的 文章 。 这 里 必须 要 传 
入 列表 ， 因 为 只 有 这 样 ，index.html 和 user.html 引用 的 _posts.html 模板 才能 在 这 个 页 面 中 
使 用 。 








固定 链接 添加 到 通用 模板 _posts.html 中 ， 显 示 在 文章 下 方 ， 如 示例 11-18 所 示 。 








示例 11-18 ”app/templates/_posts.html: 文章 的 固定 链接 


<ul class="posts"> 
{% for post in posts %} 
<li class="post"> 


<div class="post-content"> 


<div class="post-footer"> 
<a href="{{ url_for('.post', id=post.id) }}"> 
<span class="label label-default">Permalink</span> 
</a> 
</div> 
</div> 
</li> 
{% endfor %} 
</ul> 






































泻 染 固定 链接 页 面 的 post.html 模板 如 示例 11-19 所 示 ， 其 中 引入 了 上 述 模 板 。 





示例 11-19 ”app/templates/post.html: 固定 链接 模板 
{% extends "base.html" %} 


{% block title %}FLasky - Post{% endblock %} 
{% block page_content %} 


{% include '_posts.html' %} 
{% endblock %} 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
119 签 出 程序 的 这 个 版 本 。 








= 串口 
11.6 博客 文章 编辑 器 
与 博客 文章 相关 的 最 后 一 个 功能 是 文字 编辑 器 ， 它 允许 用 户 编 辑 自己 的 文章 。 博 客 文章 编 
辑 器 显示 在 单独 的 页 面 中 。 在 这 个 页 面 的 上 部 会 显示 文章 的 当前 版 本 ， 以 供 参考 ， 下 面 跟 
着 一 个 Markdown 编辑 器 ， 用 于 修改 Markdown 源 。 这 个 编辑 器 基于 Flask-PageDown 实 
现 ， 所 以 页 面 下 部 还 会 显示 一 个 编辑 后 的 文章 预览 。edit_posthtml 模板 如 示例 11-20 所 示 。 















































示例 11-20 app/templates/edit_posthtml: 编辑 博客 文章 的 模板 


{% extends "base.html" %} 
{% import "bootstrap/wtf.html" as wtf %} 


{% block title %}Flasky - Edit Post{% endblock %} 





{% block page_content %} 

<div class="page-header"> 
<h1>Edit Post</h1> 

</div> 

<div> 
{{ wtf.quick_ form(form) }} 

</div> 

{% endblock %} 


{% block scripts %} 


{{ super() }} 
{{ pagedown.include pagedown() }} 
{% endblock %} 


博客 文章 编辑 器 使 用 的 路 由 如 示例 11-21 所 示 。 





示例 11-21 app/main/views.py: 编辑 博客 文章 的 路 由 


@main.route('/edit/<int:id>', methods=['GET', 'POST']) 


@login_required 
def edit(id): 
post = Post.query.get _or_404(id) 
if current user != post.author and \ 


not current_user.can(Permission.ADMINISTER): 


abort(403) 
form = PostForm() 
if form.validate_on_submit(): 
post.body = form.body.data 
db.session.add(post) 
flash('The post has been updated.') 
return redirect(url_for('post', id=post 
form.body.data = post.body 


.id)) 


return render_template('edit post.html', form=form) 


这 个 视图 函数 的 作用 是 只 允许 博客 文章 的 作者 编辑 文章 ， 但 管理 











例外 ， 管 理 员 





编辑 所 





员 能 
有 用 户 的 文章 。 如 果 用 户 试图 编辑 其 他 用 户 的 文章 ， 视 图 函数 会 返回 403 错误 。 这 里 使 用 








的 PostForm 表单 类 和 首页 中 使 用 的 是 同一 个 。 














为 了 功能 完整 ， 我 们 还 可 以 在 每 篇 博客 文章 的 下 四 
下 的 链接 ， 如 示例 11-22 所 示 。 





























固定 链接 的 旁边 添加 一 个 指向 编辑 页 





示例 11-22 ”app/templates/_posts.html: 编辑 博客 文章 的 链接 
<UL class="posts"> 
{% for post in posts %} 
<li class="post"> 
<div class="post-content"> 
<div class="post-footer"> 
{% if current_user == post.author %} 


<a href="{{ url_for('.edit', id=post.id) }}"> 
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<span class="label label-primary">Edit</span> 
</a> 
{% elif current user.is administrator() %} 
<a href="{{ url_for('.edit', id=post.id) }}"> 
<span class="label label-danger">Edit [Admin]</span> 
</a> 
{% endif %} 
</div> 
</div> 
</li> 
{% endfor %} 
</Ul> 





通过 这 次 修改 ， 我 们 在 当前 用 户 发 布 的 博客 文章 下 面 添加 了 一 个 “Edit” 链 接 。 如 果 当 前 
用 户 是 管理 员 ， 所 有 文章 下 面 都 会 有 编辑 链接 。 为 管理 员 显示 的 链接 样式 有 点 不 同 ， 以 从 
视觉 上 表明 这 是 管理 功能 。 图 11-4 是 在 浏览 器 中 显示 的 编辑 链接 和 固定 链接 。 


如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 11h 
签 出 程序 的 这 个 版 本 。 








~ 
~ Thisis a top-level heading 
This is a regular paragraph 


miguel 


Lorem lpsum 


Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut 
laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation 
ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. 














图 11-4 博客 文章 的 编辑 链接 和 固定 链接 
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关注 者 





社交 Web 程序 允许 用 户 之 间 相 互联 系 。 在 程序 中 ， 这 种 关系 称 为 关注 者 、 好 友 、 联 系 人 、 
联络 人 或 伙伴 。 但 不 管 使 用 哪个 名 字 ， 其 功能 都 是 一 样 的， 而 且 都 要 记录 两 个 用 户 之 间 的 
定向 联系 ， 在 数据 库 查 询 中 也 要 使 用 这 种 联系 。 





在 本 章 ， 你 将 学 到 如 何在 Flasky 中 实现 关注 功能 ， 让 用 户 “ 关 注 ” 其 他 用 户 ， 并 在 首页 只 
显示 所 关注 用 户 发 布 的 博客 文章 列表 。 


12.1 再 论 数 据 库 关 系 


我 们 在 第 5 章 介绍 过 ， 数 据 库 使 用 关系 建立 记录 之 间 的 联系 。 其 中 ， 一 对 多 关系 是 最 常用 的 
关系 类 型 ， 它 把 一 个 记录 和 一 组 相关 的 记录 联系 在 一 起 。 实 现 这 种 关系 时 ， 要 在 “多 ”这 一 
侧 加 入 一 个 外 键 ， 指 向 “一 ”这 一 侧 联 接 的 记录 。 本 书 开发 的 示例 程序 现在 包含 两 个 一 对 多 
关系 : 一 个 把 用 户 角 色 和 一 组 用 户 联系 起 来 ， 另 一 个 把 用 户 和 发 布 的 博客 文章 联系 起 来 。 
大 部 分 的 其 他 关系 类 型 都 可 以 从 一 对 多 类 型 中 衍生 。 多 对 一 关系 从 “多 ”这 一 侧 看 ， 就 是 
一 对 多 关系 。 一 对 一 关系 类 型 是 简化 版 的 一 对 多 关系 ， 限 制 “ 多 ”这 一 侧 最 多 只 能 有 一 个 
记录 。 唯 一 不 能 从 一 对 多 关系 中 简单 演化 出 来 的 类 型 是 多 对 多 关系 ， 这 种 关系 的 两 侧 都 有 
多 个 记录 。 下 一 市 将 详细 介绍 多 对 多 关系 。 


12.1.1 多 对 多 关系 
一 对 多 关系 、 多 对 一 关系 和 一 对 一 关系 至 少 都 有 一 侧 是 单个 实体 ， 所 以 记录 之 间 的 联系 通 
过 外 键 实 现 ， 让 外 键 指向 这 个 实体 。 但 是 ， 你 要 如 何 实现 两 侧 都 是 “多 ”的 关系 呢 ? 
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下 面 以 一 个 典型 的 多 对 多 关系 为 例 ， 即 一 个 记录 学 生 和 他 们 所 选课 程 的 数据 库 。 很 显然 ， 
你 不 能 在 学 生 表 中 加 入 一 个 指向 课程 的 外 键 ， 因 为 一 个 学 生 可 以 选择 多 个 课程 ， 一 个 外 键 
不 够 有 用。 同样， 你 也 不 能 在 课程 表 中 加 入 一 个 指向 学 生 的 外 键 ， 因 为 一 个 课程 有 多 个 学 生 
选择 。 两 侧 都 需要 一 组 外 键 。 


这 种 问题 的 解决 方法 是 添加 第 三 张 表 ， 这 个 表 称 为 关联 表 。 现 在 ， 多 对 多 关系 可 以 分 解 成 
原 表 和 关联 表 之 间 的 两 个 一 对 多 关系 。 图 12-1 描绘 了 学 生 和 课程 之 间 的 多 对 多 关系 。 






































图 12-1 多 对 多 关系 示例 
这 个 例子 中 的 关联 表 是 registrations， 表 中 的 每 一 行 都 表示 一 个 学 生 注册 的 一 个 课程 。 





查询 多 对 多 关系 要 分 成 两 步 。 若 想 知道 某 位 学 生 选 择 了 哪些 课程 ， 你 要 先 从 学 生 和 注册 之 
间 的 一 对 多 关系 开始 ， 获 取 这 位 学 生 在 registrations 表 中 的 所 有 记录 ， 然 后 再 按照 多 到 
一 的 方向 壳 历 课程 和 注册 之 间 的 一 对 多 关系 ， 找 到 这 位 学 生 在 registrations 表 中 各 记录 
所 对 应 的 课程 。 同 样 ， 若 想 找 到 选择 了 某 门 课程 的 所 有 学 生 ， 你 要 先 从 课程 表 中 开始 ， 获 
取 其 在 registrations 表 中 的 记录 ， 再 获取 这 些 记 录 联 接 的 学 生 。 


通过 遍历 两 个 关系 来 获取 查询 结果 的 做 法 听 起 来 有 难度 ， 不 过 像 前 例 这 种 简单 关系 ， 
SQLAlchemy 就 可 以 完成 大 部 分 操作 。 图 12-1 中 的 多 对 多 关系 使 用 的 代码 表示 如 下 : 









































registrations = db.Table('registrations', 
db.Column('student_id', db.Integer, db.ForeignKey('students.id')), 
db.Column('class_id', db.Integer, db.ForeignKey('classes.id')) 

) 


class Student(db.Model): 
id = db.Column(db.Integer, primary_key=True) 
name = db.Column(db.String) 
classes = db.relationship('Class', 
secondary=registrations, 
backref=db.backref('students', lazy='dynamic'), 
lazy='dynamic') 


class Class(db.Model): 
id = db.Column(db.Integer, primary_key = True) 
name = db.Column(db.String) 


多 对 多 关系 仍 使 用 定义 一 对 多 关系 的 db.relationship() 方法 进行 定义 ， 但 在 多 对 多 关系 中 ， 
必须 把 secondary 参数 设 为 关联 表 。 多 对 多 关系 可 以 在 任何 一 个 类 中 定义 ，backref 参数 会 处 
理 好 关系 的 另 一 侧 。 关 联 表 就 是 一 个 简单 的 表 ， 不 是 模型 ，SQLAIlchemy 会 自动 接管 这 个 表 。 











classes 关系 使 用 列表 语义 ， 这 样 处 理 多 对 多 关系 特别 简单 。 假 设 学 生 是 s， 课 程 是 c， 学 
生 注 册 课 程 的 代码 为 : 








>>> s.classes.append(c) 
>>> db.session.add(s) 





列 出 学 生 s 注册 的 课程 以 及 注册 了 课程 c 的 学 生 也 很 简单 





>>> s.classes.all() 
>>> c.students.all() 


Class 模型 中 的 students 关系 由 参数 db.backref() 定义 。 注 意 ， 这 个 关系 中 还 指定 了 Lazy 
= “dynamic' 参数 ， 所 以 关系 两 侧 返 回 的 查询 都 可 接受 额外 的 过 滤器 。 














如 果 后 来 学 生 s 决定 不 选课 程 c 了 ， 那 么 可 使 用 下 面 的 代码 更 新 数据 库 ; 














>>> s.classes.remove(c) 


12.1.2 自 引 用 关系 

多 对 多 关系 可 用 于 实现 用 户 之 间 的 关注 ， 但 存在 一 个 问题 。 在 学 生 和 课程 的 例子 中 ， 关 联 
表 联 接 的 是 两 个 明确 的 实体 。 但 是 ， 表 示 用 户 关注 其 他 用 户 时 ， 只 有 用 户 一 个 实体 ， 没 有 
第 二 个 实体 。 


如 有 果 关 系 中 的 两 侧 都 在 同一 个 表 中 ， 这 种 关系 称 为 自 引 用 关系 。 在 关注 中 ， 关 系 的 左 侧 是 
用 户 实体 ， 可 以 称 为 “关注 者 ”; 关系 的 右 侧 也 是 用 户 实 体 ， 但 这 些 是 “被 关注 者 "。 从 概 
念 上 来 看 ， 自 引用 关系 和 普通 关系 没什么 区 别 ， 只 是 不 易 理 解 。 图 12-2 是 自 引 用 关系 的 数 
据 库 图 解 ， 表 示 用 户 之 间 的 关注 。 

















id 
email 
Username 














12-2 关注 者 ， 多 对 多 关系 
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本 例 的 关联 表 是 fotlows， 基 中 每 一 行 都 表示 一 个 用 户 关注 了 另 一 个 用 户 。 图 中 左边 表示 
的 一 对 多 关系 把 用 户 和 follows 表 中 的 一 组 记录 联系 起 来 ， 用 户 是 关注 者 。 图 中 右边 表示 
的 一 对 多 关系 把 用 户 和 follows 表 中 的 一 组 记录 联系 起 来 ， 用 户 是 被 关注 者 。 


12.1.3 ”高 级 多 对 多 关系 

使 用 前 一 节 介 绍 的 自 引 用 多 对 多 关系 可 在 数据 库 中 表示 用 户 之 间 的 关注 ， 但 却 有 个 限制 。 
使 用 多 对 多 关系 时 ， 往 往 需 要 存储 所 联 两 个 实体 之 间 的 额外 信息 。 对 用 户 之 间 的 关注 来 
说 ， 可 以 存储 用 户 关注 另 一 个 用 户 的 日 期 ， 这 样 就 能 按照 时 间 顺 序列 出 所 有 关注 者 。 这 种 
信息 只 能 存储 在 关联 表 中 ,但 是 在 之 前 实现 的 学 生 和 课程 之 间 的 关系 中 ， 关 联 表 完全 是 由 
SQLAlchemy 掌控 的 内 部 表 。 


为 了 能 在 关系 中 处 理 自 定义 的 数据 ， 我 们 必须 提升 关联 表 的 地 位 ， 使 其 变 成 程序 可 访问 的 
模型 。 新 的 关联 表 如 示例 12-1 所 示 ， 使 用 FoLLow 模型 表示 。 





























示例 12-1 app/models/user.py: 关注 关联 表 的 模型 实现 
class Follow(db.Model): 

__tablename _ = 'follows' 

follower_id = db.Column(db.Integer, db.ForeignKey('users.id'), 
primary_key=True) 

followed_id = db.Column(db.Integer, db.ForeignKey('users.id'), 
primary_key=True) 

timestamp = db.Column(db.DateTime, default=datetime.utcnow) 


SQLAlchemy 不 能 直接 使 用 这 个 关联 表 ， 因 为 如 果 这 么 做 程序 就 无 法 访问 其 中 的 自 定义 字 
段 。 相 反 地 ， 要 把 这 个 多 对 多 关系 的 左右 两 侧 拆 分 成 两 个 基本 的 一 对 多 关系 ， 而 且 要 定义 
成 标准 的 关系 。 代 码 如 示例 12-2 所 示 。 


示例 12-2 app/models/user.py: 使 用 两 个 一 对 多 关系 实现 的 多 对 多 关系 
class User(UserMixin, db.Model): 

ss 

followed = db.relationship('Follow', 
foreign_keys=[Follow.follower_id], 
backref=db.backref('follower', lazy='joined'), 
lazy='dynamic', 
cascade='all, delete-orphan') 

followers = db.relationship('Follow', 
foreign_keys=[Follow.followed_id], 
backref=db.backref('followed', lazy='joined'), 
lazy=' dynamic', 
cascade='all, delete-orphan') 


在 这 段 代 码 中 ，followed 和 followers 关系 都 定义 为 单独 的 一 对 多 关系 。 注 意 ， 为 了 
消除 外 键 间 的 歧义 ， 定 义 关系 时 必须 使 用 可 选 参数 foreign_keys 指定 的 外 键 。 而 且 ， 
db.backref() 参数 并 不 是 指定 这 两 个 关系 之 间 的 引用 关系 ， 而 是 回 引 FoLLow 模型 。 





回 引 中 的 Lazy 参数 指定 为 joined。 这 个 Lazy 模式 可 以 实现 立即 从 联结 查询 中 加 载 相 关 对 
象 。 例 如 ， 如 果 某 个 用 户 关注 了 100 个 用 户 ， 调 用 user.followed.all() 后 会 返回 一 个 列 
表 ， 其 中 包含 100 个 FoLLow 实例 ， 每 一 个 实例 的 follower 和 foLLowed 回 引 属性 都 指向 相 
应 的 用 户 。 设 定 为 Lazy=' joined' 模式 ， 就 可 在 一 次 数据 库 查 询 中 完成 这 些 操 作 。 如 果 把 
Lazy 设 为 默认 值 seLect， 那 么 首次 访问 follower 和 foLLowed 属性 时 才 会 加 载 对 应 的 用 户 ， 
而 且 每 个 属性 都 需要 一 个 单独 的 查询 ， 这 就 意味 着 获取 全 部 被 关注 用 户 时 需要 增加 100 次 
额外 的 数据 库 查 询 。 


这 两 个 关系 中 ，User 一 侧 设 定 的 lazy 参数 作用 不 一 样 。Lazy 参数 都 在 “一 ”这 一 侧 设 定 ， 
返回 的 结果 是 “多 ”这 一 侧 中 的 记录 。 上 述 代 码 使 用 的 是 dynamic， 因 此 关系 属性 不 会 直 
接 返 回 记 录 ， 而 是 返回 查询 对 象 ， 所 以 在 执行 查询 之 前 还 可 以 添加 额外 的 过 滤器 。 


cascade 参数 配置 在 父 对 象 上 执行 的 操作 对 相关 对 象 的 影响 。 比 如 ， 层 县 选项 可 设 定 为 : 
将 用 户 添加 到 数据 库 会 话 后 ， 要 自动 把 所 有 关系 的 对 象 都 添加 到 会 话 中 。 层 匡 选 项 的 默认 
值 能 满足 大 多 数 情况 的 需求 ， 但 对 这 个 多 对 多 关系 来 说 却 不 合用 。 删 除 对 象 时 ， 上 默认 的 层 
车 行 为 是 把 对 象 联 接 的 所 有 相关 对 象 的 外 键 设 为 空 值 。 但 在 关联 表 中 ， 删 除 记录 后 正确 的 
行为 应 该 是 把 指向 该 记录 的 实体 也 删除 ， 因 为 这 样 能 有 效 销毁 联接 。 这 就 是 层 受 选项 值 
delete-orphan 的 作用 。 
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cascade 参数 的 值 是 一 组 由 逗号 分 隔 的 层 琶 选项， 这 看 起 来 可 能 让 人 有 
点 困惑 ， 但 all 表示 除了 delete-orphan 之 外 的 所 有 层 匡 选项 。 设 为 all， 
delete-orphan 的 意思 是 启用 所 有 默认 层 县 选项 ， 而 且 还 要 删除 孤儿 记录 。 























程序 现在 要 处 理 两 个 一 对 多 关系 ， 以 便 实 现 多 对 多 关系 。 由 于 这 些 操作 经 党 需要 重复 执 
行 ， 所 以 最 好 在 User 模型 中 为 所 有 可 能 的 操作 定义 辅助 方法 。 用 于 控制 关系 的 4 个 新 方法 
如 示例 12-3 所 示 。 





示例 12-3 app/models.py: 关注 关系 的 辅助 方法 
class User(db.Model): 
# ... 
def follow(self, user): 
if not self.is_ following(user): 
f = Follow(follower=self, followed=user) 
db.session.add(f) 


def unfollow(self, user): 
f = self.followed.filter_by(followed id=user .id).first() 
tf fs 
db.session.delete(f) 


def is following(self, user): 
return self.followed.filter_by( 
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followed id=user .id).first() is not None 


def is_ followed_ by(self, user): 
return self.followers.filter_by( 
follower_id=user .id).first() is not None 


follow() 方法 手动 把 FoLLow 实例 插入 关联 表 ， 从 而 把 关注 者 和 被 关注 者 联接 起 来 ， 并 让 程 
序 有 机 会 设 定 自 定义 字段 的 值 。 联 接 在 一 起 的 两 个 用 户 被 手动 传 入 Follow 类 的 构造 器 ， 创 
建 一 个 Follow 新 实例 ， 然 后 像 往常 一 样 ， 把 这 个 实例 对 象 添加 到 数据 库 会 话 中 。 注 意 ， 
这 里 无 需 手动 设 定 timestamp 字段 ， 因 为 定义 字段 时 指定 了 默认 值 ， 即 当前 日 期 和 时 间 。 
unfollow() 方法 使 用 followed 关系 找到 联接 用 户 和 被 关注 用 户 的 FoLLow 实例 。 若 要 销毁 这 
两 个 用 户 之 间 的 联接 ， 只 需 删 除 这 个 FoLLow 对 象 即 可 。is_following() 方法 和 is_foLLowed _ 
by() 方法 分 别 在 左右 两 边 的 一 对 多 关系 中 搜索 指定 用 户 ， 如 果 找 到 了 就 返回 True。 


























如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 难 么 可 以 执行 git checkout 
12a 签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 了 一 个 数据 库 迁 移 ， 签 出 代码 后 记 
得 要 运行 python manage.py db upgrade。 








现在 ， 关 注 功能 在 数据 库 中 的 部 分 完成 了 。 你 可 以 在 GitHub 上 的 源码 仓库 找到 对 于 这 个 
数据 库 关 系 的 单元 测试 。 


12.2 ”在 资料 页 中 显示 关注 者 


如 果 用 户 查 看 一 个 尚未 关注 用 户 的 资料 页 ， 页 面 中 要 显示 一 个 “Follow” (关注 ) 按钮 ， 如 
果 查 看 已 关注 用 户 的 资料 页 则 显示 “Unfollow”( 取 消 关 注 ) 按钮 。 而 且 ， 页 面 中 最 好 能 显 
示 出 关注 者 和 被 关注 者 的 数量 ， 再 列 出 关注 和 被 关注 的 用 户 列表 ， 并 在 相应 的 用 户 资料 页 
中 显示 “Follows You”( 关 注 了 你 ) 标志 。 对 用 户 资 料 页 模板 的 改动 如 示例 12-4 所 示 。 添 
加 这 些 信息 后 的 资料 页 如 图 12-3 所 示 。 












































示例 12-4 app/templates/user.html: 在 用 户 资料 页 上 部 添加 关注 信息 
{% if current_user.can(Permission.FOLLOW) and user != current_User %} 
{% if not current user.is following(user) %} 
<a href="{{ url_for('.follow', username=user .username) }}" 
class="btn btn-primary">Follow</a> 
{% else %} 
<a href="{{ url_for('.unfollow', username=user .username) }}" 
class="btn btn-defauLt">UnfoLLow</a> 
{% endif %} 
{% endif %} 
<a href="{{ url_for('.followers', username=user .username) }}"> 
Followers: <span class="badge">{{ user.foLLowers.count() }}</span> 
</a> 
<a href="{{ url_for('.followed_by', username=user .username) }}"> 











Following: <span class="badge">{{ user.foLLowed.count() }}</span> 
</a> 
{% if current user.is_ authenticated() and user != current_ user and 
user.is_following(current_user) %} 
| <span class="label label-default">Follows you</span> 
{% endif %} 
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图 12-3 ”资料 页 中 显示 的 关注 信息 


这 次 修改 模板 用 到 了 4 个 新 端点 。 用 户 在 其 他 用 户 的 资料 页 中 点 击 “Folow” (关注 ) 按钮 
后 ， 执 行 的 是 /follow/ 《username》 路 由 。 这 个 路 由 的 实现 方法 如 示例 12-5。 





示例 12-5 app/main/views.py:“ 关 注 ” 路 由 和 视图 函数 
@main.route('/follow/<username>') 
@login_required 
@permission_required(Permission.FOLLOW) 
def foLLow(username ) : 
user = User.query.filter_by(username=username).first() 
if user is None: 
flash('Invalid user.') 
return redirect(url_for('.index')) 
if current _ user.is_ following(user): 
flash('You are already following this user.') 
return redirect(url_for('.user', Username=uysername)) 
current_user .follow(user) 
flash('You are now following %s.' % username) 
return redirect(url_for('.user', username=username)) 


这 个 视图 函数 先 加 载 请 求 的 用 户 ， 确 保 用 户 存在 且 当 前 登录 用 户 还 没有 关注 这 个 用 户 ， 然 
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后 调用 User 模型 中 定义 的 辅助 方法 follow()， 用 以 联接 两 个 用 户 。/unfollow/<username> 
路 由 的 实现 方式 类 似 。 


用 户 在 其 他 用 户 的 资料 页 中 点 击 关注 者 数量 后 ， 将 调用 /followers/<username> 路 由 。 这 个 
路 由 的 实现 如 示例 12-6 所 示 。 


示例 12-6 app/main/views.py:“ 关 注 者 ”路 由 和 视图 函数 
@main.route('/followers/<username>') 
def followers(username): 
user = User.query.filter_by(username=username).first() 
if user is None: 
flash('Invalid user.') 
return redirect(url_ for(' .index')) 
page = request.args.get('page', 1, type=int) 
pagination = User.foLLowers.paginate( 
page, per_page=current_app.config['FLASKY_FOLLOWERS_PER_PAGE'], 
error_out=False) 
follows = [{'user': item.follower, 'timestamp': item.timestamp} 
for item in pagination.items] 
return render_template('followers.html', user=user, title="Followers of", 
endpoint=' .followers', pagination=pagination, 
follows=follows) 


这 个 函数 加 载 并 验证 请 求 的 用 户 ， 然 后 使 用 第 11 章 中 介绍 的 技术 分 页 显示 该 用 户 的 
followers 关系 。 由 于 查询 关注 者 返回 的 是 FotLow 实例 列表 ， 为 了 渲染 方便 ， 我 们 将 其 转 
换 成 一 个 新 列表 ， 列 表 中 的 各 元 素 都 包含 user 和 timestamp 字段 。 














泻 染 关注 者 列表 的 模板 可 以 写 的 通用 一 些 ， 以 便 能 用 来 演 染 关注 的 用 户 列表 和 被 关注 的 用 
户 列表 。 模 板 接收 的 参数 包括 用 户 对 象 、 分 页 链接 使 用 的 端点 、 分 页 对 象 和 查询 结果 列表 。 

















foLLowed_by 端点 的 实现 过 程 几乎 一 样 ， 唯 一 区 别 在 于 : 用 户 列表 从 user.followed 关系 中 
获取 。 传 人 模板 的 参数 也 要 进行 相应 调整 。 


followers.html 模板 使 用 两 列表 格 实现 ， 左 边 一 列 用 于 显示 用 户 名 和 头像 ， 右 边 一 列 用 于 显 
示 Flask-Moment 时 间 惟 。 你 可 以 在 GitHub 上 的 源码 仓库 中 查看 具体 的 实现 代码 。 


























如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 9tt checkout 
12b 签 出 程序 的 这 个 版 本 。 








12.3 ”使 用 数据 库 联 结 查询 所 关注 用 户 的 文章 


程序 首页 目前 按时 间 降 序 显示 数据 库 中 的 所 有 文 音 。 现 在 我 们 已 经 完成 了 关注 功能 ， 如 果 


























能 让 用 户 选 择 只 查看 所 关注 用 户 发 布 的 博客 文章 就 更 好 了 。 


若 想 显示 所 关注 用 户 发 布 的 所 有 文章 ， 第 一 步 显然 先 要 获取 这 些 用 户 ， 然 后 获取 各 用 户 的 
文章 ， 再 按 一 定 顺序 排列 ， 写 和 单独 列表 。 可 是 这 种 方式 的 伸缩 性 不 好 ， 随 着 数据 库 不 断 
变 大 ， 生 成 这 个 列表 的 工作 量 也 不 断 增 长 ， 而 且 分 页 等 操作 也 无 法 高 效率 完成 。 获 取 博 客 
文章 的 高 效 方式 是 只 用 一 次 查询 。 


完成 这 个 操作 的 数据 库 操作 称 为 联结 。 联 结 操 作用 到 两 个 或 更 多 的 数据 表 ， 在 其 中 查找 满 
足 指 定 条 件 的 记录 组 合 ， 再 把 记录 组 合 插 入 一 个 临时 表 中 ， 这 个 临时 表 就 是 联结 查询 的 结 
果 。 理 解 联结 查询 的 最 好 方法 是 实例 讲解 。 


表 12-1 是 一 个 users 表示 例 ， 表 中 有 3 个 用 户 。 






































表 12-1 users 表 





id Username 
I john 

和 2 susan 

3 david 





表 12-2 是 对 应 的 posts 表 ， 表 中 有 几 篇 博客 文章 。 


表 12-2 posts 表 





id author_id body 

j 2 susan 的 博客 文章 

2 1 john 的 博客 文章 

人 3 david 的 博客 文章 

4 1 john 的 第 2 篇 博客 文章 





最 后 ， 表 12-3 显示 谁 关注 了 谁 。 从 这 个 表 中 你 可 以 看 出 ，john 关注 了 david，susan 关注 了 
john， 但 david 谁 也 没 关 注 。 


表 12-3 follows 表 


follower_id followed_id 





1 3 
和 1 
2 3 


若 想 获得 susuan 所 关注 用 户 发 布 的 文章 ， 就 要 合并 posts 表 和 follows 表 。 首 先 过 滤 
follows 表 ， 只 留 下 关注 者 为 susuan 的 记录 ， 即 上 面 表 中 的 最 后 两 行 。 然 后 过 滤 posts 表 ， 
留 下 author_id 和 过 滤 后 的 foLLows 表 中 followed_id 相等 的 记录 ， 把 两 次 过 滤 结 果 合 并 ， 
组 成 临时 联结 表 ， 这 样 就 能 高 效 查 询 susuan 所 关注 用 户 的 文章 列表 。 表 12-4 是 联结 操作 
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得 到 的 结果 。 表 中 用 来 执行 联结 操作 的 列 被 加 上 了 * 标 记 。 





表 12-4 ”联结 表 

id author_id* body follower_id followed_id* 
2 1 john 的 博客 文章 2 1 

3 | david 的 博客 文章 2 3 

4 1 john 的 第 2 篇 博客 文章 2 1 





这 个 表 中 包含 的 博客 文章 都 是 用 户 susan 所 关注 用 户 发 布 的 。 使 用 Flask-SQLAlchemy 执行 
这 个 联结 操作 的 查询 相当 复杂 : 
return db.session.query(Post).select from(Follow).\ 


filter_by(follower_id=self.id).\ 
join(Post, Follow.followed id == Post.author_id) 


你 在 此 之 前 见 到 的 查询 都 是 从 所 查询 模型 的 query 属性 开始 的 。 这 种 查询 不 能 在 这 里 使 用 ， 


因为 查询 要 返回 posts 记录 ， 所 以 首先 要 做 的 操作 是 在 follows 表 上 执行 过 滤器 。 因 此 ， 
这 里 使 用 了 一 种 更 基础 的 查询 方式 。 为 了 完全 理解 上 述 查 询 ， 下 面 分 别 说 明 各 部 分 : 





























。 db.session.query(Post) 指明 这 个 查询 要 返回 Post 对 象 ; 

。 select_from(Follow) 的 意思 是 这 个 查询 从 FoLLow 模型 开始 ; 

。 filter_by(follower_id=self.id) 使 用 关注 用 户 过 滤 foLLows 表 ; 

。 join(Post，Follow.followed_id == Post.author_id) 联结 filter_by() 得 到 的 结果 和 
Post 对 象 。 


调换 过 滤器 和 联结 的 顺序 可 以 简化 这 个 查询 : 


return Post.query.join(Follow, Follow.followed_id == Post.author_id)\ 
.filter(Follow.follower_ id == self.id) 

















如 果 首 先 执 行 联结 操作 ， 那 么 这 个 查询 就 可 以 从 Post.query 开始 ， 此 时 唯一 需要 使 用 的 两 
个 过 滤器 是 join() 和 filter()。 但 这 两 种 查询 是 一 样 的 吗 ” 先 执行 联结 操作 再 过 滤 看 起 
来 工作 量 会 更 大 一 些 ， 但 实际 上 这 两 种 查询 是 等 效 的 。SQLAlchemy 首先 收集 所 有 的 过 滤 
器 ， 然 后 再 以 最 高 效 的 方式 生成 查询 。 这 两 种 查询 生成 的 原生 SQL 指令 是 一 样 的 。 我 们 要 
把 后 一 种 查询 写 入 Post 模型 ， 如 示例 12-7 所 示 。 




















示例 12-7 app/models.py: 获取 所 关注 用 户 的 文章 
class User(db.Model): 
# ... 
@property 
def followed_ posts(self): 
return Post.query.join(Follow, Follow.followed id == Post.author_id)\ 
.filter(Follow.follower_id == self.id) 





注意 ，foLLowed_posts() 方法 定义 为 属性 ， 因 此 调用 时 无 需 加 ()。 如 此 一 来 ， 所 有 关系 的 
句法 都 一 样 了 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
12c 签 出 程序 的 这 个 版 本 。 














联结 非常 难 理解 ， 你 可 能 需要 在 shell 中 多 研究 一 下 示例 代码 才能 完全 领悟 。 


12.4 在 首页 显示 所 关注 用 户 的 文章 


现在 ， 用 户 可 以 选择 在 首页 显示 所 有 用 户 的 博客 文章 还 是 只 显示 所 关注 用 户 的 文章 了 。 示 
例 12-8 显示 了 如 何 实现 这 种 选择 。 














示例 12-8 app/main/views.py: 显示 所 有 博客 文章 或 只 显示 所 关注 用 户 的 文章 
@app.route('/', methods = ['GET', "POST']) 
def index(): 
i 
show_followed = False 
if current_user.is_authenticated(): 
show_followed = bool(request.cookies.get('show followed', '')) 
if show_followed: 
query = current_ user.followed_ posts 
else: 
query = Post.query 
pagination = query.order_by(Post.timestamp.desc()).paginate( 
page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'], 
error_out=False) 
posts = pagination.items 
return render_template('index.html', form=form, posts=posts, 
show_followed=show_followed, pagination=pagination) 





决定 显示 所 有 博客 文章 还 是 只 显示 所 关注 用 户 文 章 的 选项 存储 在 cookie 的 show_followed 
字段 中 ， 如 果 其 值 为 非 空 字符 串 ， 则 表示 只 显示 所 关注 用 户 的 文章 。cookie 以 request. 
cookies 字典 的 形式 存储 在 请 求 对 象 中 。 这 个 cookie 的 值 会 转换 成 布尔 值 ， 根 据 得 到 的 值 
设 定 本 地 变量 query 的 值 。query 的 值 决 定 最 终 获 取 所 有 博客 文章 的 查询 ， 或 是 获取 过 滤 
后 的 博客 文章 查询 。 显 示 所 有 用 户 的 文章 时 ， 要 使 用 顶级 查询 Post.query; 如 果 限 制 只 
显示 所 关注 用 户 的 文章 ， 要 使 用 最 近 添 加 的 User.foLLowed_posts 属性 。 然 后 将 本 地 变量 
query 中 保存 的 查询 进行 分 页 ， 像 往常 一 样 将 其 传 入 模板 。 























show_foLLowedcookie 在 两 个 新 路 由 中 设 定 ， 如 示例 12-9 所 示 。 


示例 12-9 app/main/views.py: 查询 所 有 文章 还 是 所 关注 用 户 的 文章 
@main.route('/all') 
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@login_required 

def show_all(): 
resp = make_response(redirect(urL_ for('.index'))) 
resp.set_cookie('show_followed', '', max_age=30*24*60*60) 
return resp 


@main.route('/followed') 

@login_required 

def show_followed(): 
resp = make_response(redirect(url for('.index'))) 
resp.set_cookie('show_followed', '1', max_age=30*24*60*60) 
return resp 


指向 这 两 个 路 由 的 链接 添加 在 首页 模板 中 。 点 击 这 两 个 链接 后 会 为 show_followedcookie 设 
定 适当 的 值 ， 然 后 重 定向 到 首页 。 


cookie 只 能 在 响应 对 象 中 设置 ， 因 此 这 两 个 路 由 不 能 依赖 Flask， 要 使 用 make_response() 
方法 创建 响应 对 象 。 


set_cookie() 国 数 的 前 两 个 参数 分 别 是 cookie 名 和 值 。 可 选 的 max_age 参数 设置 cookie 的 
过 期 时 间 ， 单 位 为 秒 。 如 果 不 指 定 参 数 max_age， 浏 览 器 关闭 后 cookie 就 会 过 期 。 在 本 例 
中 ， 过 期 时 间 为 30 天 ， 所 以 即便 用 户 几 天 不 访问 程序 ， 浏 览 器 也 会 记 住 设 定 的 值 。 


接 下 来 我 们 要 对 模板 做 些 改动 ， 在 页 面 上 部 添加 两 个 导航 选项 卡 ， 分别 调 用 /all 和 
/followed 路 由 ， 并 在 会 话 中 设 定 正确 的 值 。 你 可 在 GitHub 上 的 源码 仓库 中 查看 模板 改动 
详情 。 改 动 后 的 首页 如 图 12-4 所 示 。 























Hello, john! 


What's on your mind? 


Submit 


AI Followers 
Eh john 13 minutes ago 


This is a top-level heading 
This is a regular paragraph 














12-4 ”首页 上 显示 的 所 关注 用 户 文章 
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如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
12d 签 出 程序 的 这 个 版 本 。 











如 果 你 现在 访问 网 站 ， 切 换 到 所 关注 用 户 文章 列表 ， 会 发 现 自己 的 文章 不 在 列表 中 。 这 是 
肯定 的 ， 因 为 用 户 不 能 关注 自己 。 

虽然 查询 能 按 设计 正常 执行 ， 但 用 户 查看 好 友 文 章 时 还 是 希望 能 看 到 自己 的 文章 。 这 个 问 
题 最 简单 的 解决 办 法 是 ， 注 册 时 把 用 户 设 为 自己 的 关注 者 。 实 现 方法 如 示例 12-10 所 示 。 








示例 12-10 app/models.py: 构建 用 户 时 把 用 户 设 为 自己 的 关注 者 
class User(UserMixin, db.Model): 
# ... 
def _ init (self, **kwargs): 
# ... 
self.follow(self) 


可 是 ， 现 在 的 数据 库 中 可 能 已 经 创建 了 一 些 用 户 ， 而 且 都 没有 关注 自己 。 如 果 数 据 库 还 比 
较 小 ， 容 易 重 新 生成 ， 那 么 可 以 删 掉 再 重新 创建 。 如 果 情 况 相 反 ， 那 么 正确 的 方法 是 添加 
一 个 函数 ， 更 新 现 有 用 户 ， 如 示例 12-11 所 示 。 





示例 12-11 app/models.py: 把 用 户 设 为 自己 的 关注 者 
class User(UserMixin, db.Model): 

# ... 

@staticmethod 

def add_self_follows(): 

for user in User.query.all(): 
if not user.is following(user): 

user .follow(user) 
db.session.add(user) 
db.session.commit() 

# ... 


现在 ， 可 以 通过 在 shell 中 运行 这 个 函数 来 更 新 数据 库 : 





(venv) $ python manage.py shell 
>>> User.add_self_follows() 





创建 函数 更 新 数据 库 这 一 技术 经 常用 来 更 新 已 部 署 的 程序 ， 因 为 运行 脚本 更 新 比 手动 更 新 
数据 库 更 少 出 错 。 在 第 17 章 中 ， 你 会 看 到 如 何在 部 署 脚本 中 使 用 这 个 函数 及 类 似 函 数 。 


用 户 关 注 自 己 这 一 功能 的 实现 让 程序 变 得 更 实用 ， 但 也 有 一 些 副 作用 。 因 为 用 户 的 自 关 广 
链接 ， 用 户 资料 页 显示 的 关注 者 和 被 关注 者 的 数量 都 增加 了 1 个 。 为 了 显示 准确 ， 这 些 数 
字 要 减 去 1， 这 一 点 在 模板 中 很 容易 实现 ， 直 接 演 染 {{ user.followers.count() - 1 }} 和 
{{ user.followed.count() - 1 }} 即 可 。 然后， 还 要 调整 关注 用 户 和 被 关注 用 户 的 列表 ， 
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不 显示 自己 。 这 在 模板 中 也 容易 实现 ， 使 用 条 件 语句 即 可 。 最 后 ， 检 查 关注 者 数量 的 单元 
测试 也 会 受到 自 关注 的 影响 ， 必 须 做 出 调整 ， 计 入 自 关注 。 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 gtt checkout 
12e 签 出 程序 的 这 个 版 本 。 








下 一 章 我 们 要 实现 用 户 评论 子 系统 ， 这 是 社交 程序 的 另 一 个 重要 功能 。 





第 13 章 


用 户 评论 





允许 用 户 交互 是 社交 博客 平台 成 功 的 关键 。 在 本 章 ， 你 将 学 到 如 何 实现 用 户 评论 。 这 里 介 
绍 的 技术 基本 上 可 以 直接 用 在 大 多 数 社交 程序 中 。 


13.1 评论 在 数据 库 中 的 表示 
评论 和 博客 文章 没有 太 大 区 别 ， 都 有 正文 、 作 者 和 时 间 惟 ， 而 且 在 这 个 特定 实现 中 都 使 用 
Markdown 语法 编写 。 图 13-1 是 comments 表 的 图 解 以 及 和 其 他 数据 表 之 间 的 关系 。 
































图 13-1 博客 文章 评论 的 数据 库 表示 
评论 属于 某 篇 博客 文章 ， 因 此 定义 了 一 个 从 posts 表 到 comments 表 的 一 对 多 关系 。 使 用 这 
个 关系 可 以 获取 某 篇 特定 博客 文章 的 评论 列表 。 


comments 表 还 和 users 表 之 间 有 一 对 多 关系 。 通 过 这 个 关系 可 以 获取 用 户 发 表 的 所 有 评 
论 ， 还 能 间接 知道 用 户 发 表 了 多 少 篇 评论 。 用 户 发 表 的 评论 数量 可 以 显示 在 用 户 资料 页 
中 。Comment 模型 的 定义 如 示例 13-1。 
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示例 13-1 app/models.py: Comment 模型 


class Comment(db.Model): 
__tablename _ = 'comments' 
id = db.Column(db.Integer, primary_key=True) 
body = db.Column(db.Text) 
body_html = db.Column(db.Text) 
timestamp = db.Column(db.DateTime, index=True, default=datetime.utcnow) 
disabled = db.Column(db.Boolean) 
author_id = db.Column(db.Integer, db.ForeignKey('users.id')) 
post_id = db.Column(db.Integer, db.ForeignKey('posts.id')) 


@staticmethod 
def on_changed_body(target, value, oldvalue, initiator): 
allowed tags = ['a', 'abbr', 'acronym', 'b', 'code', 
'strong'] 
target.body_html = bleach.linkify(bleach.clean( 
markdown(value, output_ format='html'), 
tags=allowed_tags, strip=True)) 


1 ra 


em','i', 


db.event.listen(Comment.body, 'set', Comment.on_changed_body) 


Comment 模型 的 属性 几乎 和 Post 模型 一 样 ， 不 过 多 了 一 个 disablted 字段 。 这 是 个 布尔 值 字 
段 ， 协 管 员 通过 这 个 字段 查禁 不 当 评论 。 和 博客 文章 一 样 ， 评 论 也 定义 了 一 个 事件 ， 在 修 
改 body 字段 内 容 时 触发 ， 自 动 把 Markdown 文本 转换 成 HTML。 转 换 过 程 和 第 11 章 中 的 
博客 文章 一 样 ， 不 过 评论 相对 较 短 ， 而 且 对 Markdown 中 允许 使 用 的 HTML 标签 要 求 更 严 
格 ， 要 删除 与 段落 相关 的 标签 ， 只 留 下 格式 化 字符 的 标签 。 


为 了 完成 对 数据 库 的 修改 ，User 和 Post 模型 还 要 建立 与 comments 表 的 一 对 多 关系 ， 如 示 
例 13-2 所 示 。 














示例 13-2 ”app/models/user.py: users 和 posts 表 与 comments 表 之 间 的 一 对 多 关系 


class User(db.Model): 
# ... 
comments = db.relationship('Comment', backref='author', lazy='dynamic') 


class Post(db.Model): 
# ... 
comments = db.relationship('Comment', backref='post', lazy='dynamic') 


13.2 提交 和 显示 评论 

在 这 个 程序 中 ， 评论 要 显示 在 单 篇 博客 文章 页 面 中 。 这 个 页 面 在 第 11 章 添 加 固定 链接 时 
已 经 创建 。 在 这 个 页 面 中 还 要 有 一 个 提交 评论 的 表单 。 用 来 输入 评论 的 表单 如 示例 13-3 所 
示 。 这 个 表单 很 简单 ， 只 有 一 个 文本 字段 和 一 个 提交 按钮 。 





























示例 13-3 ”app/main/forms.py: 评论 输入 表单 


class CommentForm(Form) : 





body = StringField('', validators=[Required()]) 
submit = SubmitField('Submit') 


示例 13-4 是 为 了 支持 评论 而 更 新 的 /post/<int:id> 路 由 。 


示例 13-4 app/main/views.py: 支持 博客 文章 评论 
@main.route('/post/<int:id>', methods=['GET', 'POST']) 
def post(id): 
post = Post.query.get _or_404(id) 
form = CommentForm() 
if form.validate_on_submit(): 
comment = Comment(body=form.body.data, 
post=post， 
author=current_uUser. get_current_object()) 
db.session.add(comment) 
flash('Your comment has been published.') 
return redirect(url_for('.post', id=post.id, page=-1)) 
page = request.args.get('page', 1, type=int) 
if page == -1: 
page = (post.comments.count() - 1)/\ 
current_app.config['FLASKY_COMMENTS_PER_PAGE'] + 1 
pagination = post.comments.order_by(Comment.timestamp.asc()).paginate( 
page, per_page=current_app.config['FLASKY_COMMENTS_PER_PAGE'], 
error_out=False) 
comments = pagination.items 
return render_template('post.html', posts=[post], form=form, 
comments=comments, pagination=pagination) 





这 个 视图 函数 实例 化 了 一 个 评论 表单 ， 并 将 其 转 入 post.html 模板 ， 以 便 泻 染 。 提 交 表 单 
后 ， 插 入 新 评论 的 逻辑 和 处 理 博客 文章 的 过 程 差不多 。 和 Post 模型 一 样 ， 评 论 的 author 
字段 也 不 能 直接 设 为 current_user ， 因 为 这 个 变量 是 上 下 文 代理 对 象 。 真 正 的 User 对 象 要 
使 用 表达 式 current_user._get_current_object() 获取 。 





























评论 按照 时 间 改 顺序 排列 ， 新 评论 显示 在 列表 的 底部 。 提 交 评 论 后 ， 请 求 结果 是 一 个 重 定 
向 ， 转 回 之 前 的 URL， 但 是 在 urL_for() 函数 的 参数 中 把 page 设 为 -1， 这 是 个 特殊 的 页 
数 ， 用 来 请 求 评论 的 最 后 一 页 ， 所 以 刚 提交 的 评论 才 会 出 现在 页 面 中 。 程 序 从 查询 字符 串 
中 获取 页 数 ， 发 现 值 为 -1 时 ， 会 计算 评论 的 总 量 和 总 页 数 ， 得 出 真正 要 显示 的 页 数 。 

















文章 的 评论 列表 通过 post.comments 一 对 多 关系 获取 ， 按 照 时 间 惟 顺序 进行 排列 ， 再 使 
用 与 博客 文章 相同 的 技术 分 页 显示 。 评 论 列表 对 象 和 分 页 对 象 都 传人 了 模板 ， 以 便 演 染 。 
FLASKY_COMMENTS_PER_PAGE 配置 变量 也 被 加 入 config.py 中 ， 用 来 控制 每 页 显示 的 评论 数量 。 





评论 的 演 染 过 程 在 新 模板 _comments.html 中 进行 ， 类 似 于 _posts.html， 但 使 用 的 CSS 类 不 
同 。_comments.html 模板 要 引入 post.html 中 ， 放 在 文章 正文 下 方 ， 后 面 再 显示 分 页 导航 。 
你 可 以 在 GitHub 上 的 仓库 中 查看 在 这 个 程序 里 对 模板 所 做 的 改动 。 


为 了 完善 功能 ， 我 们 还 要 在 首页 和 资料 页 中 加 上 指向 评论 页 面 的 链接 ， 如 示例 13-5 所 示 。 
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示例 13-5 ”app/templates/_posts.html: 链接 到 博客 文章 的 评论 


<a href="{{ url_for('.post', id=post.id) }}#comments"> 
<span class="label label-primary"> 
{{ post.comments.count() }} Comments 
</span> 
</a> 


链接 文本 中 显示 评论 数量 的 方法 。 评 论 数 量 可 以 使 用 SQLAlchemy 提供 的 count() 过 
滤器 ep rome eg 


ee ee 这 个 链接 的 地 址 是 在 文章 的 固定 链接 后 面 加 上 一 个 
#comments 后 级 。 这 个 后 级 称 为 URL 片段 ， 用 于 指定 加 载 页 面 后 该 动 条 ee 
Web 浏览 器 会 寻 ns 
个 初始 位 置 被 设 为 post.html 模板 中 评论 区 的 标题 ， 即 <h4 ie 
显示 有 评论 的 页 面 如 图 13-2 所 示 。 


除 此 之 外 ,分 页 导航 所 用 的 宏 也 要 做 些 改动 。 评 论 的 分 页 导航 链接 也 要 加 上 #comments 片 
段 ， 因 此 在 post.html 模板 中 调用 宏 时 ， 传 入 片段 参数 。 









































如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
13a 签 出 程序 的 这 个 版 本 。 这 个 版 本 包含 了 一 个 数据 库 迁 移 ， 签 出 代码 后 记 
得 要 运行 python manage.py db upgrade。 








eee Flasky - Post ww 
LE 人 Js localhost:5000/post/3 a™ [©) 


john 20 minutes ago 


并 [2 
This is a top-level heading 
This is a regular paragraph 


Comments 


Enter your comment 


Submit 


miguel 
Congratulations! This is a great article! 


john 
5 Thank you! 














13-2 博客 文章 的 评论 
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ar AM MS 
13.3 ”管理 评论 
我 们 在 第 9 章 定义 了 儿 个 用 户 角色 ， 它 们 分 别 具 有 不 同 的 权限 。 其 中 一 个 权限 是 Permission. 
MODERATE_COMMENTS， 拥 有 此 权限 的 用 户 可 以 管理 其 他 用 户 的 评论 。 




















为 了 管理 评论 ， 我 们 要 在 导航 条 中 添加 一 个 链接 ， 具 有 权限 的 用 户 才能 看 到 。 这 个 链接 在 
base.html 模板 中 使 用 条 件 语句 添加 ， 如 示例 13-6 所 示 。 











示例 13-6 app/templatesbase.html: 在 导航 条 中 加 入 管理 评论 链接 


{% if current_user.can(Permission.MODERATE_COMMENTS) %} 
<li><a href="{{ url_for('main.moderate') }}">Moderate Comments</a></\li> 
{% endif %} 


























管理 页 面 在 同一 个 列表 中 显示 全 部 文章 的 评论 ， 最 近 发 布 的 评论 会 显示 在 前 面 。 每 篇 评 
论 的 下 方 都 会 显示 一 个 按钮 ， 用 来 切换 disabtLed 属性 的 值 。/moderate 路 由 的 定义 如 示例 
13-7 所 示 。 
































示例 13-7 app/main/views.py: 管理 评论 的 路 由 


@main.route('/moderate') 
@login_required 
@permission_required(Permission.MODERATE_COMMENTS) 
def moderate(): 
page = request.args.get('page', 1, type=int) 
pagination = Comment.query.order_by(Comment.timestamp.desc()).paginate( 
page, per_page=current_app.config['FLASKY_COMMENTS_PER_PAGE'], 
error_out=False) 
comments = pagination.items 
return render_template('moderate.html', comments=comments, 
pagination=pagination, page=page) 


这 个 函数 很 简单 ， 它 从 数据 库 中 读 取 一 页 评论 ， 将 其 传 入 模板 进行 泻 染 。 除 了 评论 列表 之 
外 ， 还 把 分 页 对 象 和 当前 页 数 传人 了 模板 。 





moderate.html 模板 也 很 简单 ， 如 示例 13-8 所 示 ， 因 为 它 依 靠 之 前 创建 的 子 模板 _comments. 
html 演 染 评论 。 

















示例 13-8 ”app/templates/moderate.html: 评论 管理 页 面 的 模板 


{% extends "base.html" %} 
{% import "_macros.html" as macros %} 


{% block title %}Flasky - Comment Moderation{% endblock %} 


{% block page_content %} 

<div class="page-header"> 
<h1>Comment Moderation</h1> 

</div> 
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{% set moderate = True %} 
{% include '_comments.html' %} 
{% if pagination %} 
<div class="pagination"> 
{{ macros.pagination widget(pagination, '.moderate') }} 
</div> 
{% endif %} 
{% endblock %} 





这 个 模板 将 演 染 评论 的 工作 交 给 _comments.html 模板 完成 ， 但 把 控制 权 交 给 从 属 模板 之 
前 ， 会 使 用 Jinja2 提供 的 set 指令 定义 一 个 模板 变量 moderate， 并 将 其 值 设 为 True。 这 个 
变量 用 在 _comments.html 模板 中 ， 决 定 是 否 演 染 评论 管理 功能 。 

















_comments.html 模板 中 显示 评论 正文 的 部 分 要 做 两 方面 修改 。 对 于 普通 用 户 ( 没 设 定 
moderate 变量 ) ， 不 显示 标记 为 有 问题 的 评论 。 对 于 协 管 员 (moderate 设 为 True)， 不 管 评 
论 是 否 被 标记 为 有 问题 ， 都 要 显示 ， 而 且 在 正文 下 方 还 要 显示 一 个 用 来 切换 状态 的 按钮 。 
具体 的 改动 如 示例 13-9 所 示 。 


示例 13-9 ”app/templates/_comments.html: 演 染 评论 的 正文 


<div class="comment-body"> 
{% if comment.disabled %} 
<p></p><i>This comment has been disabled by a moderator.</i></p> 
{% endif %} 
{% if moderate or not comment.disabled %} 
{% if comment.body_html %} 
{{ comment.body_htmL | safe }} 
{% else %} 
{{ comment.body }} 
{% endif %} 
{% endif %} 
</div> 
{% if moderate %} 
<br> 
{% if comment.disabled %} 
<a class="btn btn-default btn-xs" href="{{ url_for('.moderate enable', 
id=comment.id, page=page) }}">Enable</a> 
{% else %} 
<a class="btn btn-danger btn-xs" href="{{ url_for('.moderate disable', 
id=comment.id, page=page) }}">Disable</a> 
{% endif %} 
{% endif %} 


做 了 上 述 改 动 之 后 ， 用 户 将 看 到 一 个 关于 有 问题 评论 的 简短 提示 。 协 管 员 既 能 看 到 这 个 提 
示 ， 也 能 看 到 评论 的 正文 。 在 每 篇 评论 的 下 方 ， 协 管 员 还 能 看 到 一 个 按钮 ， 用 来 切换 评论 
的 状态 。 点 击 按钮 后 会 触发 两 个 新 路 由 中 的 一 个 ， 但 具体 触发 哪 一 个 取决 于 协 管 员 要 把 评 
论 设 为 什么 状态 。 这 两 个 新 路 由 的 定义 如 示例 13-10 所 示 。 





示例 13-10 app/main/views.py: 评论 管理 路 由 
@main.route('/moderate/enable/<int:id>') 
@login_required 
@permission_required(Permission.MODERATE_COMMENTS) 
def moderate_enable(id): 
Comment = Comment.query.get or_404(id) 
comment.disabled = False 
db.session.add(comment) 
return redirect(url_for('.moderate', 
page=request.args.get('page', 1, type=int))) 


@main.route('/moderate/disable/<int:id>') 
@login_required 
@permission_required(Permission.MODERATE_COMMENTS) 
def moderate disable(id): 
Comment = Comment.query.get or_404(id) 
comment.disabled = True 
db.session.add(comment) 
return redirect(url_for('.moderate', 
page=request.args.get('page', 1, type=int))) 


上 述 启用 路 由 和 禁用 路 由 先 加 载 评论 对 象 ， 把 disabled 字段 设 为 正确 的 值 ， 再 把 评论 对 象 
写 和 数据库。 最 后 ， 重 定向 到 评论 管理 页 面 (如 图 13-3 所 示 ) ， 如 果 查 询 字符 串 中 指定 了 
page 参数 ， 会 将 其 传人 重 定向 操作 。_comments.html 模板 中 的 按钮 指定 了 page 参数 ， 重 
定向 后 会 返回 之 前 的 页 国 
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Comment Moderation 


john aminute ago 
Thank youl 


miguel 2 minutes ago 
Congratulations! This is a great article! 


园 i 
This comment has been disabled by a moderator. 


Thank you! 


Enable 











13-3 评论 管理 页 面 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
13b 签 出 程序 的 这 个 版 本 。 








这 一 章 结束 了 对 社交 功能 的 介绍 。 下 一 章 ， 你 将 学 到 如 何以 API 的 形式 开放 程序 的 功能 ， 
从 而 让 Web 浏览 器 之 外 的 客户 端 也 能 使 用 。 
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应 用 编程 接口 





最 近 几 年 ，Web 程序 有 种 趋势 ， 那 就 是 业务 逻辑 被 越 来 越 多 地 移 到 了 客户 端 一 侧 ， 开 创 出 
了 一 种 称 为 富 互 联网 应 用 (Rich Internet Application，RIA) 的 架构 。 在 RIA 中 ， 服 务 器 的 
主要 功能 (有 时 是 唯一 功能 ) 是 为 客户 端 提供 数据 存 取 服务 。 在 这 种 模式 中 ， 服 务 器 变 成 
了 Web 服务 或 应 用 编程 接口 (Application Programming Interface，API) 。 





RIA 可 采用 多 种 协议 与 Web 服务 通信 。 远 程 过 程 调用 (Remote Procedure Cal，RPC) 协议 ， 
例如 XML-RPC， 及 由 其 衍生 的 简单 对 象 访问 协议 (Simplified Object Access Protocol，SOAP)， 
在 几 年 前 比较 受 欢迎 。 最 近 ， 表 现 层 状态 转移 (Representational State Transfer，REST) 架构 因 
露头 角 ， 成 为 Web 程序 的 新 宠 ， 因 为 这 种 架构 建立 在 大 家 熟识 的 万 维 网 基础 之 上 。 











Flask 是 开发 REST 架构 Web 服务 的 理想 框架 ， 因 为 Flask 天 生 轻 量 。 在 本 章 ， 你 将 学 到 
如 何 使 用 Flask 实现 符合 REST 架构 的 API。 


14.1 REST 简 介 


Roy Fielding 在 其 博士 论文 (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style. 
htm) 中 介绍 了 Web 服务 的 REST 架构 方式 ， 并 列 出 了 6 个 符合 这 一 架构 定义 的 特征 。 





客户 痛 - 服 务 器 

客户 端 和 服务 器 之 间 必 须 有 明确 的 界线 。 
无 状态 
客户 端 发 出 的 请 求 中 必须 包含 所 有 必要 的 信息 。 服 务 器 不 能 在 两 次 请 求 之 间 保存 客户 端 
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的 任何 状态 。 


缓存 
服务 器 发 出 的 响应 可 以 标记 为 可 缓存 或 不 可 缓存 ， 这 样 出 于 优化 目的 ， 客 户 端 (或 客户 
端 和 服务 器 之 间 的 中 间 服务 ) 可 以 使 用 缓存 。 





接口 统一 

客户 端 访 问 服务 器 资源 时 使 用 的 协议 必须 一 致 ， 定 义 良 好 ， 且 已 经 标准 化 。REST Web 
服务 最 常 使 用 的 统一 接口 是 HITP 协议 。 

系统 分 层 

在 客户 端 和 服务 器 之 间 可 以 按 需 插 入 代理 服务 器 、 缓 存 或 网 关 ， 以 提高 性 能 、 稳 定性 和 
伸缩 性 。 




















按 需 代码 
客户 端 可 以 选择 从 服务 器 上 下 载 代 码 ， 在 客户 端的 环境 中 执行。 


14.1.1 资源 就 是 一 切 

资源 是 REST 架构 方式 的 核心 概念 。 在 REST 架构 中 ， 资 源 是 程序 中 你 要 着 重 关 注 的 事物 。 
例如 ， 在 博客 程序 中 ， 用 户 、 博 客 文章 和 评论 都 是 资源 。 

每 个 资源 都 要 使 用 唯一 的 URL 表示 。 还 是 以 博客 程序 为 例 ， 一 篇 博客 文章 可 以 使 用 URL / 
api/posts/12345 表示 ， 其 中 12345 是 这 篇 文章 的 唯一 标识 符 ， 使 用 文章 在 数据 库 中 的 主键 
表示 。URL 的 格式 或 内 容 无 关 紧 要 ， 只 要 资源 的 URL 只 表示 唯一 的 一 个 资源 即 可 。 

















某 一 类 资源 的 集合 也 要 有 一 个 URL。 博 客 文 章 集合 的 URL 可 以 是 /api/posts/， 评 论 集合 的 
URL 可 以 是 /api/comments/。 





API 还 可 以 为 某 一 类 资源 的 逻辑 子 集 定义 集合 URL。 例 如 ， 编 号 为 12345 的 博客 文章 ， 其 
中 的 所 有 评论 可 以 使 用 URL /api/posts/12345/comments/ 表示 。 表 示 资 源 集合 的 URL 习惯 
在 末端 加 上 一 个 斜 线 ， 代 表 一 种 “文件 夹 ”结构 。 


注意 ，Flask 会 特殊 对 待 末 端 带 有 和 斜 线 的 路 由 。 如 果 客 户 端 请 求 的 URL 的 末 
端 没有 和 斜 线 ， 而 唯一 匹配 的 路 由 末端 有 和 斜 线 ，Flask 会 自动 响应 一 个 重 定向 ， 
转向 末端 带 斜 线 的 URL。 反 之 则 不 会 重 定向 。 











14.1.2 请求 方法 
客户 端 程序 在 建立 起 的 资源 URL 上 发 送 请 求 ， 使 用 请 求 方法 表示 期 望 的 操作 。 若 要 从 博 





客 API 中 获取 现 有 博客 文章 的 列表 ， 客 户 端 可 以 向 http:/www.exam-ple.com/api/posts/ 发 
送 GET 请 求 。 若 要 插入 一 篇 新 博客 文章 ， 客 户 端 可 以 向 同一 地 址 发 送 PosT 请 求 ， 而 且 请 求 
主体 中 要 包含 博客 文章 的 内 容 。 若 要 获取 编号 为 12345 的 博客 文章 ， 客 户 端 可 以 向 http:// 
www.example.com/api/posts/12345 发 送 GET 请 求 。 表 14-1 列 出 了 REST 架构 API 中 常用 的 


请 求 方法 及 其 含义 。 





表 14-1 REST 架 构 API 中 使 用 的 HTTP 请 求 方法 


























请 求 方法 目 标 说 ” 明 HTTP 状 态 码 
GET 单个 资源 的 URL ”获取 目标 资源 200 
拓 取 资源 的 集合 务 器 实现 了 分 页 ， 就 是 一 
资源 集合 的 URL 获取 次 源 的 集合 (如果 服 务 器 实现 了 分 页 ， 就 是 一 页 中 ob 
的 资源 ) 
_ 创建 新 资源 ， 并 将 其 加 入 目标 集合 。 服 务 器 为 新 资源 指 
POST 资源 集合 的 URL ， SR 201 
全 人 派 URL， 并 在 响应 的 Location 首部 中 返回 
ee 修改 一 个 现 有 资源 。 如 果 客 户 端 能 为 资源 指派 URL， 还 
PUT 单个 资源 的 URL Se 20 
9 资源 的 URL 可 用 来 创建 新 资源 
DELETE 单个 资源 的 URL I 除 一 个 资源 200 
DELETE 资源 集合 的 URL I 除 目标 集合 中 的 所 有 资源 200 





























REST 架构 不 要 求 必须 为 一 个 资源 实现 所 有 的 请 求 方法 。 如 果 资 源 不 支持 
客户 端 使 用 的 请 求 方法 ， 响 应 的 状态 码 为 405， 返 回 “ 不 允许 使 用 的 方法 ”。 
Flask 会 自动 处 理 这 种 错误 。 








14.1.3 请求 和 响应 主体 


在 请 求 和 响应 的 主体 中 ， 资 源 在 客户 端 和 服务 器 之 间 来 








回 传送 ， 但 REST 没有 指定 编码 


资源 的 方式 。 请 求 和 响应 中 的 Content-Type 首部 用 于 指明 主体 中 资源 的 编码 方式 。 使 用 
HTTP 协议 中 的 内 容 协商 机 制 ， 可 以 找到 一 种 客户 端 和 服务 器 都 支持 的 编码 方式 。 





REST Web 服务 常用 的 两 种 编码 方式 是 JavaScript 对 象 表示 法 (JavaScript Object Notation ， 
JSON) 和 可 扩展 标记 语言 (Extensible Markup Language，XML)。 对 基于 Web 的 RIA 来 


说 ，JSON 更 具 吸 引力 ， 





因为 JSON 和 JavaScript 联系 紧密 ， 而 JavaScript 是 Web 浏 


[es 


网 奉 


使 用 的 客户 端 脚本 语言 。 继 续 以 博客 API 为 例 ， 一 篇 博客 文章 对 应 的 资源 可 以 使 用 如 下 的 


JSON 表示 : 


C 


"url": "http://www.example.com/api/posts/12345", 
"title": "Writing RESTful APIs in Python", 


"author": "http://www.example.com/api/users/2", 
"body": "... text of the article here ...", 
"comments": "http://www.example.com/api/posts/12345/comments" 
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注意 ， 在 这 篇 博客 文章 中 ，url、author 和 comments 字段 都 是 完整 的 资源 URL。 这 是 很 重 
要 的 表示 方法 ， 因 为 客户 端 可 以 通过 这 些 URL 发 据 新 资源 。 





在 设计 良好 的 REST API 中 ， 客 户 端 只 需 知 道 几 个 顶级 资源 的 URL， 其 他 资源 的 URL 则 从 响 
应 中 包含 的 链接 上 发 据 。 这 就 好 比 浏 览 网 络 时 ， 你 在 自己 知道 的 网 页 中 点 击 链 接 发 据 新 网 页 。 


14.1.4 版 本 

在 传统 的 以 服务 器 为 中 心 的 Web 程序 中 ， 服 务 器 完全 和 掌控 程序 。 更 新 程序 时 ， 只 需 在 服务 
器 上 部 署 新 版 本 就 可 更 新 所 有 的 用 户 ， 因 为 运行 在 用 户 Web 浏览 器 中 的 那 部 分 程序 也 是 从 
服务 器 上 下 载 的 。 


但 升级 RIA 和 Web 服务 要 复杂 得 多 ， 因 为 客户 端 程序 和 服务 器 上 的 程序 是 独立 开发 的 ， 
有 时 其 至 由 不 同 的 人 进行 开发 。 你 可 以 考虑 一 下 这 种 情况 ， 即 一 个 程序 的 REST Web 服 
务 被 很 多 客户 端 使 用 ， 其 中 包括 Web 浏览 器 和 智能 手机 原生 应 用 。 服 务 器 可 以 随时 更 新 
Web 浏览 器 中 的 客户 端 ， 但 无 法 强制 更 新 智能 手机 中 的 应 用 ， 更 新 前 先 要 获得 机 主 的 许 
可 。 即 便 机 主 想 进行 更 新 ， 也 不 能 保证 新 版 应 用 上 传 到 所 有 应 用 商店 的 时 机 都 完全 吻合 新 
服务 器 端 版 本 的 部 署 。 


基于 以 上 原因 ，Web 服务 的 容错 能 力 要 比 一般 的 Web 程序 强 ， 而 且 还 要 保证 旧版 客户 端 
能 继续 使 用 。 这 一 问题 的 常见 解决 办 法 是 使 用 版 本 区 分 Web 服务 所 处 理 的 URL。 例 如 ， 
首次 发 布 的 博客 Web 服务 可 以 通过 /api/v1.0/posts/ 提供 博客 文章 的 集合 。 















































在 URL 中 加 入 Web 服务 的 版 本 有 助 于 条 理化 管理 新 旧 功 能 ， 让 服务 器 能 为 新 客户 端 提供 
新 功能 ， 同 时 继续 支持 旧版 客户 端 。 博 客服 务 可 能 会 修改 博客 文章 使 用 的 JSON 格式 ， 同 
时 通过 /api/v1.1/posts/ 提供 修改 后 的 博客 文章 ， 而 客户 端 仍 能 通过 /api/v1.0/posts/ 获取 旧 的 
JSON 格式 。 在 一 段 时 间 内 ， 服 务 器 要 同时 处 理 v1.1 和 v1.0 这 两 个 版 本 的 URL。 


















































提供 多 版 本 支持 会 增加 服务 器 的 维护 负担 ， 但 在 某 些 情况 下 ， 这 是 不 破坏 现 有 部 署 且 能 让 
程序 不 断 发 展 的 唯一 方式 。 

















14.2 ”使 用 Flask 提 供 REST Web 服 务 


使 用 Flask 创建 REST Web 服务 很 简单 。 使 用 熟悉 的 route() 修饰 器 及 其 methods 可 选 参 
数 可 以 声明 服务 所 提供 资源 URL 的 路 由 。 处 理 JSON 数据 同样 简单 ， 因 为 请 求 中 包含 的 
JSON 数据 可 通过 request.json 这 个 Python 字典 获取 ， 并 且 需 要 包含 JSON 的 响应 可 以 使 
用 Flask 提供 的 辅助 函数 jsonify() 从 Python 字典 中 生成 。 




















以 下 几 节 将 介绍 如 何 扩展 Flasky， 创 建 一 个 REST Web 服务 ， 以 便 让 客户 端 访问 博客 文章 
及 相关 资源 。 





14.2.1 创建 API 蓝 


REST API 相关 的 路 由 是 一 个 自 成 一 体 的 程序 子 集 ， 所 以 为 了 更 好 地 组 织 代 码 ， 我 们 最 好 
把 这 些 路 由 放 到 独立 的 蓝本 中 。 这 个 程序 API 蓝本 的 基本 结构 如 示例 14-1 所 示 。 


示例 14-1 API 蓝本 的 结构 
| -fLasky 
| -app/ 
|-api_1 .0 
|-_init .py 
-Users.py 
-posts.py 
-Comments .py 
-authentication.py 
-errors.py 
-decorators.py 














注意 ，API 包 的 名 字 中 有 一 个 版 本 号 。 如 果 需 要 创建 一 个 向 前 兼容 的 API 版 本 ， 可 以 添加 
一 个 版 本 号 不 同 的 包 ， 让 程序 同时 支持 两 个 版 本 的 API。 


在 这 个 API 蓝本 中 ， 各 资源 分 别 在 不 同 的 模块 中 实现 。 蓝 本 中 还 包含 处 理 认 证 、 错 误 以 及 
提供 自 定义 修饰 器 的 模块 。 蓝 本 的 构造 文件 如 示例 14-2 所 示 。 




















示例 14-2 app/api_1_0/_init .py: API 蓝本 的 构造 文件 
from fLask import Blueprint 


api = BLueprint('apt'，_name__) 


from . import authentication, posts, users, comments, errors 
注册 API 蓝本 的 代码 如 示例 14-3 所 示 。 


示例 14-3 app/_init .py: 注册 API 蓝本 
def create_app(config_name) : 
# ... 
from .api_ 1 0 import api as api 1 0_blueprint 
app.register_blueprint(api 1 0_blueprint, url_prefix='/api/v1.0') 
# ... 


14.2.2 ”错误 处 理 
REST Web 服务 将 请 求 的 状态 告知 客户 端 时 ， 会 在 响应 中 发 送 适 当 的 HTTP 状态 码 ， 并 将 
额外 信息 放 入 响应 主体 。 客 户 端 能 从 Web 服务 得 到 的 常见 状态 码 如 表 14-2 所 示 。 
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表 14-2 API 返回 的 常见 HTTP 状 态 码 











HTTP 状 态 码 ”名 称 说 明 

200 OK (成 功 ) 请 求 成 功 完成 

201 Created (已 创建 ) 请 求 成 功 完 成 并 创建 了 一 个 新 资源 
400 Bad request ( 坏 请 求 ) 请 求 不 可 用 或 不 一 致 

401 Unauthorized (未 授权 ) 请 求 未 包含 认证 信息 

403 Forbidden (禁止 ) 请 求 中 发 送 的 认证 密令 无 权 访问 目标 
404 Notfound (未 找到 ) URL 对 应 的 资源 不 存在 

405 Method not allowed (不 允许 使 用 的 方法 ) 指定 资源 不 支持 请 求 使 用 的 方法 

500 Internal server error (内 部 服务 器 错误 ) 处 理 请 求 的 过 程 中 发 生意 外 错误 














处 理 404 和 500 状态 码 时 会 有 点 小 麻烦 ， 因 为 这 两 个 错误 是 由 Flask 自己 生成 的 ， 而 且 一 
般 会 返回 HTML 响应 ， 这 很 可 能 会 让 API 客户 端 困惑 。 


为 所 有 客户 端 生成 适当 响应 的 一 种 方法 是 ， 在 错误 处 理 程序 中 根据 客户 端 请 求 的 格式 改写 
响应 ， 这 种 技术 称 为 内 容 协 商 。 示 例 14-4 是 改进 后 的 404 错误 处 理 程序 ， 它 向 Web 服务 
客户 端 发 送 JSON 格式 响应 ， 除 此 之 外 都 发 送 HTML 格式 响应 。500 错误 处 理 程序 的 写法 
类 似 。 


示例 14-4 app/main/errors.py: 使 用 HTTP 内 容 协 商 处 理 错误 


@main.app_errorhandler(404) 
def page_not_found(e): 
if request.accept mimetypes.accept_json and \ 
not request.accept mimetypes.accept_html: 
response = jsonify({'error': 'not found'}) 
response.status_code = 404 
return response 
return render_template('404.html'), 404 


















































这 个 新 版 错误 处 理 程 序 检查 Accept 请 求 首部 (Werkzeug 将 其 解码 为 request.accept_ 
mimetypes)， 根 据 首部 的 值 决定 客户 端 期 望 接收 的 响应 格式 。 浏 览 器 一 般 不 限制 响应 的 格 
式 ， 所 以 只 为 接受 JSON 格式 而 不 接受 HTML 格式 的 客户 端 生 成 JSON 格式 响应 。 





其 他 状态 码 都 由 Web 服务 生成 ， 因 此 可 在 蓝本 的 errors.py 模块 作为 辅助 函数 实现 。 示 例 
14-5 是 403 错误 的 处 理 程序 ， 其 他 错误 处 理 程序 的 写法 类 似 。 





示例 14-5 ”app/api_1_0/errors.py: API 蓝本 中 403 状态 码 的 错误 处 理 程序 


def forbidden(message): 
response = jsonify({'error': 'forbidden', 'message': message}) 
response.status_code = 403 
return response 








现在 ，Web 服务 的 视图 函数 可 以 调用 这 些 辅 助 函 数 生成 错误 响应 了 。 











14.2.3 使 用 Flask-HTTPAuth 认 证 用 户 

和 普通 的 Web 程序 一 样 ，Web 服务 也 需要 保护 信息 ， 确 保 未 经 授权 的 用 户 无 法 访问 。 为 
此 ，RIA 必须 询问 用 户 的 登录 密令 ， 并 将 其 传 给 服务 器 进行 验证 。 

我 们 前 面 说 过 ，REST Web 服务 的 特征 之 一 是 无 状态 ， 即 服务 器 在 两 次 请 求 之 间 不 能 “ 记 
住 ” 客 户 端 的 任何 信息 。 客 户 端 必 须 在 发 出 的 请 求 中 包含 所 有 必要 信息 ， 因 此 所 有 请 求 都 


必须 包含 用 户 密令 。 











程序 当前 的 登录 功能 是 在 Flask-Login 的 帮助 下 实现 的 ， 可 以 把 数据 存储 在 用 户 会 话 中 。 默 
认 情 况 下 ，Flask 把 会 话 保存 在 客户 端 cookie 中 ， 因 此 服务 器 没有 保存 任何 用 户 相关 信息 ， 
都 转交 给 客户 端 保存 。 这 种 实现 方式 看 起 来 遵守 了 REST 架构 的 无 状态 要 求 ， 但 在 REST 
Web 服务 中 使 用 cookie 有 点 不 现实 ， 因 为 Web 浏览 器 之 外 的 客户 端 很 难 提供 对 cookie 的 
支持 。 鉴 于 此 ， 使 用 cookie 并 不 是 一 个 很 好 的 设计 选择 。 


























REST 架构 的 无 状态 要 求 看 起 来 似乎 过 于 严格 ， 但 这 并 不 是 随意 提出 的 要 
求 ， 无 状态 的 服务 器 伸缩 起 来 更 加 简单 。 如 果 服 务 器 保存 了 客户 端的 相关 信 
县， 就 必须 提供 一 个 所 有 服务 器 都 能 访问 的 共享 缓 在， 这 样 才能 保证 一 直 使 
用 同一 台 服 务 器 处 理 特 定 客 户 端的 请 求 。 这 样 的 需求 很 难 实现 。 























因为 REST 架构 基于 HITP 协议 ， 所 以 发 送 密令 的 最 佳 方式 是 使 用 HTTP 认证 ， 基 本 认证 
和 摘要 认证 都 可 以 。 在 HTTP 认证 中 ， 用 户 密令 包含 在 请 求 的 Authorization 首部 中 。 








HTTP 认证 协议 很 简单 ， 可 以 直接 实现 ， 不 过 Flask-HTTPAuth 扩展 提供 了 一 个 便利 的 包 
装 ， 可 以 把 协议 的 细节 隐藏 在 修饰 器 之 中 ， 类 似 于 Flask-Login 提供 的 login_required 修 


Flask-HTTPAuth 使 用 pip 安装 : 
(venv) $ pip install fLask-httpauth 


在 将 HTTP 基本 认证 的 扩展 进行 初始 化 之 前 ， 我 们 先 要 创建 一 个 HTTPBasicAuth 类 对 象 。 
和 Flask-Login 一 样 ，Flask-HTTPAuth 不 对 验证 用 户 密令 所 需 的 步骤 做 任何 假设 ， 因 此 所 
需 的 信息 在 回调 函数 中 提供 。 示 例 14-6 展示 了 如 何 初始 化 Flask-HTTPAuth 扩展 ， 以 及 如 
何在 回调 函数 中 验证 密令 。 


示例 14-6 ”app/api_1_0/authentication.py: 初始 化 Flask-HTTPAuth 


from fLask.ext.httpauth import HTTPBasicAuth 
auth = HTTPBasicAuth() 


@auth.verify_password 
def verify_password(email, password): 
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if email == 
g.current_user = AnonymousUser() 
return True 
User = User.query.filter_by(email = email).first() 
if not user: 
return False 
g.current_user = user 
return user.verify_password(password) 








由 于 这 种 用 户 认 证 方法 只 在 API 蓝本 中 使 用 ， 所 以 Flask-HTTPAuth 扩展 只 在 蓝本 包 中 初 
始 化 ， 而 不 像 其 他 扩展 那样 要 在 程序 包 中 初始 化 。 


电子 邮件 和 密码 使 用 User 模型 中 现 有 的 方法 验证 。 如 果 登 录 密 令 正确 ， 这 个 验证 回调 函数 
就 返回 True， 和 否则 返回 Fatse。API 蓝本 也 支持 匿名 用 户 访问 ， 此 时 客户 端 发 送 的 电子 邮 
件 字段 必须 为 空 。 


验证 回调 函数 把 通过 认证 的 用 户 保存 在 Flask 的 全 局 对 象 9 中 ， 如 此 一 来 ， 视 图 函数 便 能 
进行 访问 。 注 意 ， 匿 名 登录 时 ， 这 个 函数 返回 True 并 把 Flask-Login 提供 的 anonymousUser 
类 实例 赋值 给 g.current_user。 















































由 于 每 次 请 求 时 都 要 传送 用 户 密令 ， 所 以 API 路 由 最 好 通过 安全 的 HITP 提 
供 ， 加 密 所 有 的 请 求 和 响应 。 





如 果 认 证 密令 不 正确 ， 服 务 器 向 客户 端 返回 401 错误 。 默 认 情 况 下 ，Flask-HTTPAnuth 自 
动 生成 这 个 状态 码 ， 但 为 了 和 API 返回 的 其 他 错误 保持 一 致 ， 我 们 可 以 自 定 义 这 个 错误 响 
应 ， 如 示例 14-7 所 示 。 





示例 14-7 app/api_1_0/authentication.py: Flask-HTTPAuth 错误 处 理 程序 


Qauth.error_handLer 
def auth_error() : 
return unauthorized('Invalid credentials') 


为 保护 路 由 ， 可 使 用 修饰 器 auth.1login_required: 


Qapi.route('/posts/') 
@auth. Login_required 
def get_posts() : 

pass 


不 过 ， 这 个 蓝本 中 的 所 有 路 由 都 要 使 用 相同 的 方式 进行 保护 ， 所 以 我 们 可 以 在 before_ 
request 处 理 程序 中 使 用 一 次 Login_required 修饰 器 ， 应 用 到 整个 蓝本 ， 如 示例 14-8 所 示 。 


示例 14-8 ”app/api_1_0/authentication.py: 在 before_request 处 理 程序 中 进行 认证 


from .errors import forbidden_error 





Qapi.before_request 
@auth. login_required 
def before_request(): 
if not g.current user.is_anonymous and \ 
not g.current_ user.confirmed: 
return forbidden('Unconfirmed account') 


现在 ，API 蓝本 中 的 所 有 路 由 都 能 进行 自动 认证 。 而 且 作 为 附加 认证 ，before_request 处 
理 程序 还 会 拒绝 已 通过 认证 但 没有 确认 账户 的 用 户 。 














14.2.4 ”基于 令 牌 的 认证 
每 次 请 求 时 ， 客 户 端 都 要 发 送 认 证 密令 。 为 了 避免 总 是 发 送 敏 感 信息 ， 我 们 可 以 提供 一 种 
基于 令 牌 的 认证 方案 。 


使 用 基于 令 牌 的 认证 方案 时 ， 客 户 端 要 先 把 登录 密令 发 送 给 一 个 特殊 的 URL， 从 而 生成 
认证 令 牌 。 一 旦 客户 端 获 得 令 牌 ， 就 可 用 令 牌 代替 登录 密令 认证 请 求 。 出 于 安全 考虑 ， 令 
牌 有 过 期 时 间 。 令 牌 过 期 后 ， 客 户 端 必 须 重 新 发 送 登 录 密 令 以 生成 新 令 牌 。 令 牌 落 入 他 人 
之 手 所 带 来 的 安全 隐患 受 限于 令 牌 的 短暂 使 用 期 限 。 为 了 生成 和 验证 认证 令 牌 ， 我 们 要 在 
User 模型 中 定义 两 个 新 方法 。 这 两 个 新 方法 用 到 了 itsdangerous 包 ， 如 示例 14-9 所 示 。 








示例 14-9 app/models.py: 支持 基于 令 牌 的 认证 
class User(db.Model): 
# ... 
def generate_auth_token(self, expiration): 
s = Serializer(current_app.config['SECRET_KEY'], 
expires_in=expiration) 
return s.dumps({'id': self.id}) 


@staticmethod 
def verify_auth_token(token): 
s = Serializer(current_app.config['SECRET_KEY']) 
try: 
data = s.Loads(token) 
except: 
return None 
return User.query.get(data[ 'id']) 


generate_auth_token() 方法 使 用 编码 后 的 用 户 id 字段 值 生成 一 个 签名 令 牌 ， 还 指定 了 以 秒 
为 单位 的 过 期 时 间 。verify_auth_token() 方法 接受 的 参数 是 一 个 令 牌 ， 如 果 令 牌 可 用 就 返 
回 对 应 的 用 户 。verify_auth_token() 是 静态 方法 ， 因 为 只 有 解码 令 牌 后 才能 知道 用 户 是 谁 。 





为 了 能 够 认证 包含 令 牌 的 请 求 ， 我 们 必须 修改 Flask-HTTPAuth 提供 的 verify_password 回 
调 ， 除 了 普通 的 密令 之 外 ， 还 要 接受 令 牌 。 修 改 后 的 回调 如 示例 14-10 所 示 。 
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示例 14-10 ”app/api_1_0/authentication.py: 支持 令 牌 的 改进 验证 


@auth.verify_password 
def verify_password(email_or_token, password): 
if email_or_token == '': 
g.current_user = AnonymousUser() 
return True 
if password == 
g.current_user = User.verify auth_ token(email_or_token) 
g.token_used = True 
return g.current_user is not None 
User = User.query.filter_by(email=email_or_token).first() 
if not User : 
return False 
g.current_user = USser 
g.token_used = False 
return user.verify_password(password) 


Li 




















在 这 个 新 版 本 中 ， 第 一 个 认证 参数 可 以 是 电子 邮件 地 址 或 认证 令 牌 。 如 果 这 个 参数 为 空 ， 
那 就 和 之 前 一 样 ， 假 定 是 匿名 用 户 。 如 果 密 码 为 空 ， 那 就 假定 email_or_token 参数 提供 的 
是 令 牌 ， 按 照 令 牌 的 方式 进行 认证 。 如 果 两 个 参数 都 不 为 空 ， 假 定 使 用 常规 的 邮件 地 址 和 
密码 进行 认证 。 在 这 种 实现 方式 中 ， 基 于 令 牌 的 认证 是 可 选 的 ， 由 客户 端 决 定 是 否 使 用 。 
为 了 让 视图 函数 能 区 分 这 两 种 认证 方法 ， 我 们 添加 了 9.token_used 变量 。 











把 认证 令 牌 发 送 给 客户 端的 路 由 也 要 添加 到 API 蓝本 中 ， 具体 实现 如 示例 14-11 所 示 。 


示例 14-11 app/api_1_0/authentication.py: 生成 认证 令 牌 
Qapi.route(' /token ') 
def get_ token(): 
if g.current user.is anonymous() or g.token_used: 
return unauthorized('Invalid credentials') 
return jsonify({'token': g.current_user.generate_ auth_token( 
expiration=3600),'expiration': 3600}) 














由 于 这 个 路 由 也 在 蓝本 中 ， 所 以 添加 到 before_request 处 理 程序 上 的 认证 机 制 也 会 用 在 这 
个 路 由 上 。 为 了 避免 客户 端 使 用 旧 令 牌 申请 新 令 牌 ， 要 在 视图 函数 中 检查 g.token_used 变 
量 的 值 ， 如 果 使 用 令 牌 进行 认证 就 拒绝 请 求 。 这 个 视图 函数 返回 JSON 格式 的 响应 ， 基 中 
包含 了 过 期 时 间 为 1 小 时 的 令 牌 。JSON 格式 的 响应 也 包含 过 期 时 间 。 





























14.2.5 ”资源 和 JSON 的 序列 化 转换 


开发 Web 程序 时 ， 经 常 需要 在 资源 的 内 部 表示 和 JSON 之 间 进 行 转换 。JSON 是 HTTP 请 
求 和 响应 使 用 的 传输 格式 。 示 例 14-12 是 新 添加 到 Post 类 中 的 to_json( ) 方法 。 


示例 14-12 ”app/models.py: 把 文章 转换 成 JSON 格式 的 序列 化 字典 


class Post(db.Model): 
# ... 
def to_json(self): 





json_post = { 
'url': url_for('api.get post', id=self.id, external=True), 
'body': self.body, 
'body_html': self.body_html, 
'timestamp': self.timestamp, 
'author': url_for('api.get user', id=self.author_id, 
_externaL=True) ， 
'comments': url_for('api.get post_ comments', id=self.id, 
_external=True) 
'comment_count': self.comments.count() 
} 


return json_post 
urL、author 和 comments 字段 要 分 别 返 回 各 自 资源 的 URL， 因 此 它们 使 用 urt_for() 生 
成 ， 所 调用 的 路 由 即将 在 API 蓝本 中 定义 。 注 意 ， 所 有 url_for() 方法 都 指定 了 参数 _ 
external=True， 这 么 做 是 为 了 生成 完整 的 URL， 而 不 是 生成 传统 Web 程序 中 经 常 使 用 的 
相对 URL。 











这 段 代码 还 说 明 表示 资源 时 可 以 使 用 虚构 的 属性 。comment_count 字段 是 博客 文章 的 评论 
数量 ， 并 不 是 模型 的 真实 属性 ， 它 之 所 以 包含 在 这 个 资源 中 是 为 了 便于 客户 端 使 用 。 


User 模型 的 to_json() 方法 可 以 按照 Post 模型 的 方式 定义 ， 如 示例 14-13 所 示 。 











示例 14-13 app/models.py: 把 用 户 转换 成 JSON 格式 的 序列 化 字典 


class User(UserMixin, db.Model): 
# ... 
def to_json(self): 
json_user = { 
'url': url_for('api.get post', id=self.id, external=True), 
'username': self.username, 
'member_since': self.member_since, 
'last_seen': self.last_seen, 
'posts': url_for('api.get user_posts', id=self.id, external=True), 
'followed_posts': url_for('api.get user_followed posts', 
id=self.id, _external=True), 
"post_count ' : self.posts.count() 
} 


return json_user 


注意 ， 为 了 保护 隐私 ， 这 个 方法 中 用 户 的 某 些 属性 没有 加 入 响应 ， 例 如 ematt 和 role。 这 
段 代码 再 次 说 明 ， 提 供给 客户 端的 资源 表示 没 必 要 和 数据 库 模 型 的 内 部 表示 完全 一 致 。 


把 JSON 转换 成 模型 时 面临 的 问题 是 ， 客 户 端 提供 的 数据 可 能 无 效 、 错 误 或 者 多 余 。 示 例 
14-14 是 从 JSON 格式 数据 创建 Post 模型 实例 的 方法 。 





示例 14-14 ”app/models.py: 从 JSON 格式 数据 创建 一 篇 博客 文章 


from app.exceptions import ValidationError 


class Post(db.Model): 





应 用 编程 接口 | 163 








斋 
@staticmethod 
def from_ json(json_post): 
body = json_post.get('body') 
if body is None or body == "': 
raise ValidationError('post does not have a body') 
return Post(body=body) 


如 你 所 见 ， 上 述 代 码 在 实现 过 程 中 只 选择 使 用 JSON 字典 中 的 body 属性 ， 而 把 body_html 
属性 忽略 了 ， 因 为 只 要 body 属性 的 值 发 生变 化 ， 就 会 触发 一 个 SQLAlchemy 事件 ， 自 动 
在 服务 器 端 这 染 Markdown。 除 非 允 许 客户 端 倒 填 日 期 〈 这 个 程序 并 不 提供 此 功能 ) ， 否 则 
无 需 指定 timestamp 属性 。 由 于 客户 端 无 权 选 择 博客 文章 的 作者 ， 所 以 没有 使 用 author 字 
段 。author 字段 唯一 能 使 用 的 值 是 通过 认证 的 用 户 。comments 和 comment_count 属性 使 用 
数据 库 关系 自动 生成 ， 因 此 其 中 没有 创建 模型 所 需 的 有 用 信息 。 最 后 ，url 字段 也 被 忽略 
了 ， 因 为 在 这 个 实现 中 资源 的 URL 由 服务 器 指派 ， 而 不 是 客户 端 。 






































注意 如 何 检 查 错 误 。 如 果 没 有 body 字 段 或 者 其 值 为 空 fron_json() 方 法 会 抛 出 
ValidationError 异常 。 在 这 种 情况 下 ， 抛 出 异常 才 是 处 理 错误 的 正确 方式 ， 因 为 from_json() 
方法 并 没有 掌握 处 理 问 题 的 足够 信息 ， 唯 有 把 错误 交 给 调用 者 ， 由 上 层 代码 处 理 这 个 错误 。 
ValidationError 类 是 Python 中 ValueError 类 的 简单 子 类 ， 具 体 定义 如 示例 14-15 所 示 。 












































示例 14-15 app/exceptions.py: ValidationError 异常 


class ValidationError(ValueError): 
pass 














现在 ， 程 序 需要 向 客户 端 提供 适当 的 响应 以 处 理 这 个 异常 。 为 了 避免 在 视图 国 数 中 编写 捕 
获 异常 的 代码 ， 我 们 可 创建 一 个 全 局 异常 处 理 程序 。 对 于 ValidationError 异常 ， 其 处 理 
程序 如 示例 14-16 所 示 。 



































示例 14-16 app/api_1_0/errors.py: API 中 ValidationError 异常 的 处 理 程序 


@api .errorhandler(ValidationError) 
def validation error(e): 
return bad_request(e.args[0]) 


这 里 使 用 的 errorhandter 修饰 器 和 注册 HTTP 状态 码 处 理 程 序 时 使 用 的 是 同一 个 ， 只 不 过 
此 时 接收 的 参数 是 Exception 类 ， 只 要 抛 出 了 指定 类 的 异常 ， 就 会 调用 被 修饰 的 函数 。 注 
意 ， 这 个 修饰 器 从 API 蓝本 中 调用 ， 所 以 只 有 当 处 理 蓝 本 中 的 路 由 时 抛 出 了 异常 才 会 调用 
这 个 处 理 程序 。 


使 用 这 个 技术 时 ， 视 图 函数 中 得 代码 可 以 写 得 十 分 简洁 明 ， 而 且 无 需 检查 错误 。 例 如 : 








@api .route('/posts/', methods=['POST']) 
def new_post(): 
post = Post.from json(request.json) 
post.author = g.current_user 





db.session.add(post) 
db.session.commit() 
return jsonify(post.to_json()) 


14.2.6 ”实现 资源 端点 
现在 我 们 需要 实现 用 于 处 理 不 同 资源 的 路 由 。GET 请 求 往往 是 最 简单 的 ， 因 为 它们 只 返回 
信息 ， 无 需 修改 信息 。 示 例 14-17 是 博客 文章 的 两 个 GET 请 求 处 理 程序 。 


























示例 14-17 app/api_1_0/posts.py: 文章 资源 GET 请 求 的 处 理 程序 


Qapi.route('/posts/ ') 
@auth. login_required 
def get_posts(): 
posts = Post.query.all() 
return jsonify({ 'posts': [post.to_json() for post in posts] }) 


@api.route('/posts/<int:id>') 

@auth. login_required 

def get_ post(id): 
post = Post.query.get or_404(id) 
return jsonify(post.to_json()) 


第 一 个 路 由 处 理 获取 文章 集合 的 请 求 。 这 个 函数 使 用 列表 推导 生成 所 有 文章 的 JSON 版 本 。 
第 二 个 路 由 返回 单 篇 博客 文章 ， 如 果 在 数据 库 中 没 找到 指定 id 对 应 的 文章 ， 则 返回 404 
错误 。 

















404 错误 的 处 理 程序 在 程序 层 定 义 ， 如 果 客 户 端 请 求 JSON 格式 ， 就 要 返回 
JSON 格式 响应 。 如 果 要 根据 Web 服务 定制 响应 内 容 ， 也 可 在 API 蓝本 中 重 
新 定义 404 错误 处 理 程序 。 























博客 文章 资源 的 P05T 请 求 处 理 程序 把 一 篇 新 博客 文章 插入 数据 库 。 路 由 的 定义 如 示例 
14-18 所 示 。 


示例 14-18 ”app/api_1_0/posts.py: 文章 资源 POST 请 求 的 处 理 程序 


@api.route('/posts/', methods=['POST']) 
@permission_required(Permission.WRITE_ARTICLES) 
def new_post(): 

post = Post.from_json(request.json) 

post.author = g.current_user 

db.session.add(post) 

db.session.commit() 

return jsonify(post.to_json()), 201, \ 

{'Location': url_for('api.get post', id=post.id, external=True)} 





这 个 视图 函数 包含 在 permission_required 修饰 器 (下面 的 示例 中 会 定义 ) 中 ， 确 保 通过 
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认证 的 用 户 有 写 博 客 文章 的 权限 。 得 益 于 前 面 实现 的 错误 处 理 程序 ， 创 建 博客 文章 的 过 程 
变 得 很 直观 。 博 客 文章 从 JSON 数据 中 创建 ， 其 作者 就 是 通过 认证 的 用 户 。 这 个 模型 写 入 
数据 库 之 后 ， 会 返回 201 状态 码 ， 并 把 Location 首部 的 值 设 为 刚 创建 的 这 个 资源 的 URL。 


注意 ， 为 便于 客户 端 操 作 ， 响 应 的 主体 中 包含 了 新 建 的 资源 。 如 此 一 来 ， 客 户 端 就 无 需 在 
创建 资源 后 再 立即 发 起 一 个 GET 请 求 以 获取 资源 。 








ie 


























用 来 防止 未 授权 用 户 创建 新 博客 文章 的 permission_required 修饰 器 和 程序 中 使 用 的 类 似 ， 
但 会 针对 API 蓝本 进行 自 定义 。 具 体 实 现 如 示例 14-19 所 示 。 


示例 14-19 app/api_1_0/decorators.py: permission_required 修饰 器 
def permission required(permission): 
def decorator(f): 
@wraps(f) 
def decorated_function(*args, **kwargs): 
if not g.current_user.can(permission): 
return forbidden('Insufficient permissions') 
return f(*args, **kwargs) 
return decorated function 
return decorator 





博客 文章 PUT 请 求 的 处 理 程序 用 来 更 新 现 有 资源 ， 如 示例 14-20 所 示 。 





示例 14-20 ”app/api_1_0/posts.py: 文章 资源 PUT 请 求 的 处 理 程序 
Qapi.route('/posts/<int:id>' ，methods=['PUT']) 
@permission_required(Permission.WRITE_ARTICLES) 
def edit post(id): 
post = Post.query.get_or_404(id) 
if g.current user != post.author and \ 
not g.current_user.can(Permission.ADMINISTER): 
return forbidden('Insufficient permissions') 
post.body = request.json.get('body', post.body) 
db.session.add(post) 
return jsonify(post.to_json()) 





本 例 中 要 进行 的 权限 检查 更 为 复杂 。 修 饰 器 用 来 检查 用 户 是 否 有 写 博 客 文章 的 权限 ， 但 为 
了 确保 用 户 能 编辑 博客 文章 ， 这 个 国 数 还 要 保证 用 户 是 文章 的 作者 或 者 是 管理 员 。 这 个 检 
查 直接 添加 到 视图 函数 中 。 如 果 这 种 检查 要 应 用 于 多 个 视图 函数 ， 为 避免 代码 重复 ， 最 好 
的 方法 是 为 其 创建 修饰 器 。 





























因为 程序 不 允许 删除 文章 ， 所 以 没 必 要 实现 DELETE 请 求 方法 的 处 理 程序 。 




















用 户 资源 和 评论 资源 的 处 理 程序 实现 方式 类 似 。 表 14-3 列 出 了 这 个 程序 要 实现 的 资源 。 你 
可 到 GitHub 仓库 (https://github.com/miguelgrinberg/flasky) 中 获取 完整 的 实现 ， 以 便 学 习 
研究 。 





表 14-3 ”Flasky API 资 源 
































资源 URL 方 法 说 明 

/users/<int:id> GET 三 个 用 户 

/users/<int:id>/posts/ GET 个 用 户 发 布 的 博客 文章 
/users/<int:id>/timeline/ GET 个 用 户 所 关注 用 户 发 布 的 文章 
/posts/ GET、 POST 所 有 博客 文章 

/posts/<int:id> GET、 PUT 一 篇 博客 文章 
/posts/<int:id/>comments/ GET、 POST 一 篇 博客 文章 中 的 评论 
/comments/ GET 所 有 评论 

/comments/<int:id> GET 一 篇 评论 


注意 ， 这 些 资 源 只 允许 客户 端 实现 Web 程序 提供 的 部 分 功能 。 支 持 的 资源 可 以 按 需 扩展 ， 


比如 说 提供 关注 者 资源 、 支 持 评论 管理 ， 以 及 实现 客户 端 需要 的 其 他 功能 。 


14.2.7 分 页 大 型 资源 集合 














对 大 型 资源 集合 来 说 ， 获 取 和 集合 的 GET 请 求 消耗 很 大 ， 而 且 难 以 管理 。 和 Web 程序 一 样 ， 








Web 服务 也 可 以 对 集合 进行 分 页 。 
示例 14-21 是 分 页 博客 文章 列表 的 一 种 实现 方式 。 


示例 14-21 app/api_1_0/posts.py: 分 页 文章 资源 
@api.route('/posts/') 
def get_posts(): 
page = request.args.get('page', 1, type=int) 
pagination = Post.query.paginate( 
page, per_page=current_app.config['FLASKY_POSTS_PER_PAGE'], 
error_out=False) 
posts = pagination.items 
prev = None 
if pagination.has_prev: 
prev = url_for('api.get posts', page=page-1, _external=True) 
next = None 
if pagination.has_next: 
next = url_for('api.get posts', page=page+1, _external=True) 
return jsonify({ 
'posts': [post.to json() for post in posts], 
'prev': prev, 
'next': next, 
'count': pagination.total 


}) 





JSON 格式 响应 中 的 posts 字段 依旧 包含 各 篇 文章 ， 但 现在 这 只 是 完整 集合 的 一 部 分 。 如 
果 资 源 有 上 一 页 和 下 一 页 ，prev 和 next 字段 分 别 表示 上 一 页 和 下 一 页 资源 的 URL。count 


是 集合 中 博客 文章 的 总 数 。 
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这 种 技术 可 应 用 于 所 有 返回 集合 的 路 由 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
14a 签 出 程序 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 你 还 要 运行 pip install 


-rT requirements/dev.txt。 





14.2.8 使 用 HTTPie 测 试 Web 服 务 
测试 Web 服务 时 必须 使 用 HTTP 客户 端 。 最 常 使 用 的 两 个 在 命令 行 中 测试 Web 服务 的 客 
户 端 是 curl 和 HTTPie。 后 者 的 命令 行 更 简洁 ， 可 读 性 也 更 高 。HTTPie 使 用 pip 安装 : 





(venv) $ pip install httpie 
GET 请 求 可 按照 如 下 的 方式 发 起 : 


(venv) $ http --json --auth <email>:<password> GET \ 
> http://127.0.0.1:5000/api/v1.0/posts 

HTTP/1.0 200 OK 

Content-Length: 7018 

Content-Type: application/json 

Date: Sun, 22 Dec 2013 08:11:24 GMT 

Server: Werkzeug/0.9.4 Python/2.7.3 


{ 
"posts": [ 
]， 
"prev": null 
"next": "http://127.0.0.1:5000/api/v1.0/posts/?page=2", 
"count": 150 
} 


注意 响应 中 的 分 页 链接 。 因 为 这 是 第 一 页 ， 所 以 没有 上 一 页 ， 不 过 返回 了 获取 下 一 页 的 
URL 和 总 数 。 





匿名 用 户 可 发 送 空 邮 件 地 址 和 密码 以 发 起 相同 的 请 求 : 


(venv) $ http --json --auth : GET http://127.0.0.1:5000/api/v1.0/posts/ 





下 面 这 个 命令 发 送 P05T 请 求 以 添加 一 篇 新 博客 文章 : 


(venv) $ http --auth <email>:<password> --json POST \ 
> http://127.0.0.1:5000/api/v1.0/posts/ \ 

> "body=I'm adding a post from the *command line*." 
HTTP/1.0 201 CREATED 

Content-Length: 360 

Content-Type: application/json 

Date: Sun, 22 Dec 2013 08:30:27 GMT 





Location: http://127.0.0.1:5000/api/v1.0/posts/111 
Server: Werkzeug/0.9.4 Python/2.7.3 


{ 
"author": "http://127.0.0.1:5000/api/v1.0/users/1" ， 
"body": "I'm adding a post from the *command line*.", 


"body_html": "<p>I'm adding a post from the <em>command line</em>.</p>", 


"comments": "http://127.0.0.1:5000/api/v1.0/posts/111/comments", 
"comment_count": 0， 
"timestamp": "Sun, 22 Dec 2013 08:30:27 GMT", 
"url": "http://127.0.0.1:5000/api/v1.0/posts/111" 
} 


要 想 使 用 认证 令 牌 ， 可 向 /api/v1.0/token 发 送 请 求 : 


(venv) $ http --auth <email>:<password> --json GET \ 
> http://127.0.0.1:5000/api/v1.0/token 

HTTP/1.0 200 OK 

Content-Length: 162 

Content-Type: application/json 

Date: Sat, 04 Jan 2014 08:38:47 GMT 

Server: Werkzeug/0.9.4 Python/3.3.3 


{ 


"expiration": 3600, 


"token": "eyJpYXQi0jEzODg4MjQ3MjcsImV4cCI6MTMAODgyODMyNywiYWxnIjoiSFMy..." 


} 


在 接 下 来 的 1 小 时 中 ， 这 个 令 牌 可 用 于 访问 API， 请 求 时 要 和 空 密码 一 起 发 送 : 


(venv) $ http --json --auth eyJpYXQ...: GET http://127.0.0.1:5000/api/v1.0/posts/ 


令 牌 过 期 后 ， 请 求 会 返回 401 错误 ， 表 示 需 要 获取 新 令 牌 。 








次 你 ! 我 们 在 这 一 章 结束 了 第 二 部 分 ， 至 此 ，Flasky 的 功能 开发 阶段 就 完全 结束 了 。 很 
显然 ， 下 一 步 我 们 要 部 署 Flasky。 在 部 署 过 程 中 ， 我 们 会 遇 到 新 的 挑战 ， 这 就 是 第 三 部 分 





的 主题 。 
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第 三 部 分 





成 功 在 望 


第 15 章 


测试 





编写 单元 测试 主要 有 两 个 目的 。 实 现 新 功能 时 ， 单 元 测试 能 够 确保 新 添加 的 代码 按 预 期 方 
式 运 行 。 当 然 ， 这 个 过 程 也 可 手动 完成 ， 不 过 自动 化 测试 显然 能 有 效 闻 省 时 间 和 精力 。 








另外 ， 一 个 更 重要 的 目的 是 ， 每 次 修改 程序 后 ， 运 行 单元 测试 能 保证 现 有 代码 的 功能 没有 
有 退化。 也 就 是 说 ， 改 动 没 有 影响 原 有 代码 的 正常 运行 。 

在 最 开始 ， 单 元 测试 就 是 Flasky 开发 的 一 部 分 ， 我 们 为 数据 库 模型 类 中 实现 的 程序 功能 编 
写 了 测试 。 模 型 类 很 容易 在 运行 中 的 程序 上 下 文 之 外 进行 测试 ， 因 此 不 用 花费 太 多 精力 ， 
为 数据 库 模型 中 实现 的 全 部 功能 编写 单元 测试 ， 这 有 至 少 能 有 效 保证 程序 这 部 分 在 不 断 完 善 
的 过 程 中 仍 能 按 预 期 运行 。 

在 本 章 ， 我 们 将 讨论 如 何 改进 、 增 强 单元 测试 。 


15.1 获取 代码 覆盖 报告 

编写 测试 组 件 很 重要 ， 但 知道 测试 的 好 坏 同 样 重要 。 代 码 覆 盖 工 具 用 来 统计 单元 测试 检查 
了 多 少 程序 功能 ， 并 提供 一 个 详细 的 报告 ， 说 明 程 序 的 哪些 代码 没有 测试 到 。 这 个 信息 非 
常 重要 ， 因 为 它 能 指引 你 为 最 需要 测试 的 部 分 编写 新 测试 。 




















Python 提供 了 一 个 优秀 的 代码 覆盖 工具 ， 称 为 coverage， 你 可 以 使 用 pip 进行 安装 : 
(venv) $ pip install coverage 


这 个 工具 本 身 是 一 个 命令 行 脚本 ， 可 在 任何 一 个 Python 程序 中 检查 代码 覆盖 。 除 此 之 外 ， 
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它 还 提供 了 更 方便 的 脚本 访问 功能 ， 使 用 编程 方式 启动 覆盖 检查 引擎 。 为 了 能 更 好 地 把 覆 
盖 检 测 集成 到 启动 脚本 manage.py 中 ， 我 们 可 以 增强 第 7 章 中 自 定义 的 test 命令 ,添加 可 
选 选项 --coverage。 这 个 选项 的 实现 方式 如 示例 15-1 所 示 。 


示例 15-1 manage.py: 覆盖 检测 

#!/usr/bin/env python 

import os 

COV = None 

if os.environ.get('FLASK_COVERAGE'): 
import coverage 
COV = coverage.coverage(branch=True, include='app/*') 
COV.start() 


# ... 


@manager .command 
def test(coverage=False): 
"" "Run the unit tests. 
if coverage and not os.environ.get('FLASK_COVERAGE ' ) : 
import sys 
os.environ['FLASK_COVERAGE'] = '1" 
os.execvp(sys.executable, [sys.executable] + sys.argv) 
import unittest 
tests = unittest.TestLoader().discover('tests') 
unittest.TextTestRunner(verbosity=2).run(tests) 
if COV: 
COV.stop() 
COV.save() 
print('Coverage Summary: ') 
COV.report() 
basedir = os.path.abspath(os.path.dirname(__file )) 
covdir = os.path.join(basedir, 'tmp/coverage') 
COV.html_report(directory=covdir) 
print('HTML version: file://%s/index.html' % covdir) 
COV.erase() 


# ... 





在 Flask-Script 中 ， 自 定义 命令 很 简单 。 若 想 为 test 命令 添加 一 个 布尔 值 选 项 ， 只 需 在 
test() 国 数 中 添加 一 个 布尔 值 参 数 即 可 。Flask-Script 根据 参数 名 确定 选项 名 ， 并 据 此 向 函 
数 中 传 入 True 或 False。 


不 过 ， 把 代码 覆盖 集成 到 manage.py 脚本 中 有 个 小 问题 。test() 函数 收 到 - -coverage 选项 
的 值 后 再 启动 覆盖 检测 已 经 晚 了 ， 那 时 全 局 作用 域 中 的 所 有 代码 都 已 经 执行 了 。 为 了 检测 
的 准确 性 ， 设 定 完 环境 变量 FLASK_COVERAGE 后 ， 脚 本 会 重启 。 再 次 运行 时 ， 脚 本 顶端 的 代 
码 发 现 已 经 设 定 了 环境 变量 ， 于 是 立即 启动 覆盖 检测 。 

















国 数 coverage.coverage() 用 于 启动 覆盖 检测 引擎 。branch=True 选项 开启 分 支 履 盖 分 析 ， 
除了 跟踪 哪 行 代 码 已 经 执行 外 ， 还 要 检查 每 个 条 件 语句 的 True 分 支 和 False 分 支 是 否 都 执 





行 了 。include 选项 用 来 限制 程序 包 中 文件 的 分 析 范 














围 ， 只 对 这 些 文件 中 的 代码 进行 覆盖 








检测 。 如 果 不 指定 inctude 选项 ， 虚 拟 环境 中 安装 的 全 部 扩展 和 测试 代码 都 会 包含 进 覆 盖 


报告 中 ， 给 报告 添加 很 多 杂项 。 
执行 完 所 有 测试 后 ，text() 函数 会 在 终端 输出 报告 ， 


同时 还 会 生成 一 个 使 用 HTML 编写 


的 精美 报告 并 写 入 硬盘 。HTML 格式 的 报告 非常 适合 直观 形象 地 展示 覆盖 信息 ， 因 为 它 按 





照 源 码 的 使 用 情况 给 代码 行 加 上 了 不 同 的 颜色 。 








-rr requirements/dev.txt, 





文本 格式 的 报告 示例 如 下 : 


(venv) $ python manage.py test --coverage 


Ran 19 tests in 50.609s 


如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15a 签 出 程序 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 你 还 要 运行 pip install 


OK 

Coverage Summary: 

Name Stmts Miss Branch BrMiss Cover Missing 
app/__init _ 33 0 0 0 100% 
app/api_1_ 0/__init 3 0 0 0 100% 
app/api_1_0/authentication 30 19 和 1 27% 
app/api_1_0/comments 40 30 12 12 19% 
app/api_1_0/decorators 11 3 2 2 62% 
app/api_1 0/errors 7 10 0 0 41% 
app/api_1_0/posts 35 23 9 9 27% 
app/api_1_0/users 30 24 12 了 2 14% 
app/auth/__init_ _ 3 0 0 0 100% 
app/auth/forms 45 8 8 8 70% 
app/auth/views 109 84 41 41 17% 
app/decorators 14 3 2 2 69% 
app/email 15 9 0 0 40% 
app/exceptions 2 0 0 9 100% 
app/main/__init__ 6 1 0 0 83% 
app/main/errors 20 15 9 9 17% 
app/main/forms 39 7 8 8 68% 
app/main/views 169 131 36 36 19% 
app/models 243 62 44 17 72% 
TOTAL 864 429 194 167 44% 


HTML version: file:///home/flask/flasky/tmp/coverage/index.html 


上 述 报 告 显示 ， 整 体 覆 盖 率 为 4%。 情 况 并 不 遭 ， 但 也 不 太 好 。 现 阶段 ， 模 型 类 是 单元 
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测试 的 关注 焦点 ， 它 共 包 含 243 个 语句 ， 测 试 覆盖 了 其 中 72% 的 语句 。 很 明显 ，main 和 
auth 蓝本 中 的 views.py 文件 以 及 api_1_9 监 本 中 的 路 由 的 覆盖 率 都 很 低 ， 因 为 我 们 没有 为 
这 些 代 码 编写 单元 测试 。 














有 了 这 个 报告 ， 我们 就 能 很 容易 确定 向 测试 组 件 中 添加 哪些 测试 以 提高 覆盖 率 。 但 遗憾 的 
是 ， 并 非 程序 的 所 有 组 成 部 分 都 像 数 据 库 模 型 那样 易于 测试 。 在 接 下 来 的 两 节 ， 我 们 将 介 
绍 更 高 级 的 测试 策略 ， 可 用 于 测试 视图 函数 、 表 单 和 模板 。 





注意 ， 出 于 排版 芳 虑 ， 上 述 示例 报告 省 略 了 “Missing” 列 的 内 容 。 这 一 列 显示 负 试 没有 用 
盖 的 源码 行 ， 是 一 个 由 行 号 范围 组 成 的 长 列表 。 














15.2 “Flask 测 试 客户 端 


程序 的 某 些 代码 严重 依赖 运行 中 的 程序 所 创建 的 环境 。 例 如 ， 你 不 能 直接 调用 视图 函数 
中 的 代码 进行 测试 ， 因 为 这 个 函数 可 能 需要 访问 Flask 上 下 文 全 局 变量 ， 如 request 或 
session; 视图 函数 可 能 还 等 待 接收 PosT 请 求 中 的 表单 数据 ， 而 且 某 些 视图 函数 要 求 用 户 
先 登 录 。 简 而 言 之 ， 视 图 函数 只 能 在 请 求 上 下 文 和 运行 中 的 程序 里 运行 。 









































Flask 内 建 了 一 个 测试 客户 医用 于 解决 (至 少 部 分 解决 ) 这 一 问题 。 测 试 客户 端 能 复 现 程 
序 运行 在 Web 服务 器 中 的 环境 ， 让 测试 扮演 成 客户 端 从 而 发 送 请 求 。 

在 测试 客户 端 中 运行 的 视图 函数 和 正常 情况 下 的 没有 太 大 区 别 ， 服 务 器 收 到 请 求 ， 将 其 分 
配给 适当 的 视图 函数 ， 视 图 函数 生成 响应 ， 将 其 返回 给 测试 客户 端 。 执 行 视图 函数 后 ， 生 
成 的 啊 应 会 传人 测试 ， 检 查 是 否 正确 。 








15.2.1 测试 Web 程 序 
示例 15-2 是 一 个 使 用 测试 客户 端 编写 的 单元 测试 框架 。 





示例 15-2 tests/test_client.py: 使 用 Flask 测试 客户 端 编 写 的 测试 框架 
import unittest 
from app import create app, db 
from app.models import User, Role 


class FlaskClientTestCase(unittest.TestCase): 
def setUp(self): 

self.app = create app('testing') 
self.app_context = self.app.app_context() 
self.app_context.push() 
db.create_all() 
Role.insert_roles() 
self.client = seLf.app.test_cLient(use_cookies=True) 


def tearDown(self): 





db.session.remove() 
db.drop_all() 
self.app_context.pop() 


def test_home_page(seLf ) : 
response = self.client.get(url_for('main.index')) 
self.assertTrue('Stranger' in response.get data(as_text=True)) 


测试 用 例 中 的 实例 变量 self.client 是 Flask 测试 客户 端 对 象 。 在 这 个 对 象 上 可 调用 方法 向 
程序 发 起 请 求 。 如 果 创 建 测试 客户 端 时 启用 了 use_cookies 选项 ， 这 个 测试 客户 端 就 能 像 
浏览 器 一 样 接收 和 发 送 cookie， 因 此 能 使 用 依赖 cookie 的 功能 记 住 请 求 之 间 的 上 下 文 。 值 
得 一 提 的 是 ， 这 个 选项 可 用 来 启用 用 户 会 话 ， 让 用 户 登录 和 退出 。 














test_home_page() 测试 作为 一 个 简单 的 例子 演示 了 测试 客户 端的 作用 。 在 这 个 例子 
中 ， 客 户 端 向 首页 发 起 了 一 个 请 求 。 在 测试 客户 端 上 调用 get() 方法 得 到 的 结果 是 一 个 
FlaskResponse 对 象 ， 内 容 是 调用 视图 函数 得 到 的 响应 。 为 了 检查 测试 是 否 成 功 ， 要 在 响应 
主体 中 搜索 是 否 包含 "stranger" 这 个 词 。 响 应 主体 可 使 用 response.get_data() 获取 ， 而 
"Stranger" 这 个 词 包含 在 向 匿名 用 户 显示 的 欢迎 消息 “Hello, Stranger!” 中 。 注 意 ， 默 认 
情况 下 get_data() 得 到 的 响应 主体 是 一 个 字 节 数组 ， 传 入 参数 as_text=True 后 得 到 的 是 
一 个 更 易于 处 理 的 Unicode 字符 串 。 








测试 客户 端 还 能 使 用 post() 方法 发 送 包 含 表 单数 据 的 PosT 请 求 ， 不 过 提交 表单 时 会 有 一 
个 小 麻烦 。Flask-WTF 生成 的 表单 中 包含 一 个 隐藏 字段 ， 其 内 容 是 CSRF 令 牌 需要 和 表 
单 中 的 数据 一 起 提交 。 为 了 复 现 这 个 功能 ， 测 试 必须 请 求 包含 表单 的 页 面 ， 然 后 解析 响应 
返回 的 HTML 代码 并 提取 令 牌 ， 这样 才 能 把 令 牌 和 表单 中 的 数据 一 起 发 送 。 为 了 避免 在 测 
试 中 处 理 CSRF 令 牌 这 一 烦琐 操作 ， 最 好 在 测试 配置 中 禁用 CSRF 保护 功能 ， 如 示例 15-3 
所 示 。 











示例 15-3 ”config.py: 在 测试 配置 中 禁用 CSRF 保护 


class TestingConfig(Config): 
#... 
WTF_CSRF_ENABLED = False 


示例 15-4 是 一 个 更 为 高 级 的 单元 测试 ， 模 拟 了 新 用 户 注册 账户 、 登 录 、 使 用 确认 令 牌 确认 
账户 以 及 退出 的 过 程 。 


示例 15-4 tests/test_client.py: 使 用 Flask 测试 客户 端 模拟 新 用 户 注册 的 整个 流程 
class FlaskClientTestCase(unittest.TestCase): 
# ... 
def test_register_and_login(self): 
# 注册 新 账户 


response = self.client.post(url_for('auth.register'), data={ 





'email': 'john@example.com', 
'username': 'john', 
"password': 'cat', 
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'password2': "cat' 


}) 


self.assertTrue(response.status_code == 302) 


# 使 用 新 注册 的 账户 登录 
response = self.client.post(url_for('auth.login'), data={ 
'email': 'john@example.com', 
'password': 'cat' 
}, follow_redirects=True) 
data = response.get data(as_text=True) 
self.assertTrue(re.search('Hello,\s+john!', data)) 
seLf .assertTrue('You have not confirmed your account yet' in data) 


# 发 送 确认 令 牌 

user = User.query.filter_by(email='john@example.com').first() 

token = user.generate confirmation_ token() 

response = self.client.get(url_for('auth.confirm', token=token), 
follow_redirects=True) 

data = response.get data(as_text=True) 

self.assertTrue('You have confirmed your account' in data) 





# 退出 
response = self.client.get(url_for('auth.Tlogout'), 

follow_redirects=True) 
data = response.get data(as_text=True) 


seLf .assertTrue('You have been logged out' in data) 





这 个 测试 先 向 注册 路 由 提交 一 个 表单 。post() 方法 的 data 参数 是 个 字典 ， 包 含 表单 中 的 
各 个 字段 ， 各 字段 的 名 字 必 须 严格 匹配 定义 表单 时 使 用 的 名 字 。 由 于 CSRF 保护 已 经 在 测 
试 配置 中 禁用 了 ， 因 此 无 需 和 表单 数据 一 起 发 送 




















/auth/register 路 由 有 两 种 响应 方式 。 如 果 注 册 数 据 可 用 ， 会 返回 一 个 重 定向 ， 把 用 户 转 到 
登录 页 面 。 注 册 不 可 用 的 情况 下 ， 返 回 的 啊 应 会 再 次 泻 染 注册 表单 ， 而 且 还 包含 适当 的 错 
误 消 息 。 为 了 确认 注册 成 功 ， 测 试 会 检查 响应 的 状态 码 是 否 为 302， 这 个 代码 表示 重 定向 。 


这 个 测试 的 第 二 部 分 ed dc in re psn sp 这 一 工作 通过 
向 /auth/login 路 由 发 起 P05T 请 求 完 成 。 这 一 次 ， 调 用 post() 方法 时 指定 了 参数 follow_ 
redirects=True， 让 测试 客户 端 和 浏览 器 < 自动 向 重 定向 的 URL 发 起 GET 请 求 。 指 定 
这 个 参数 后 ， 返 回 的 不 是 302 状态 码 ， 而 是 请 求 重 定 向 的 URL 返回 的 响应 。 


成 功 登 录 后 的 响应 应 该 是 一 个 页 面 ， 显 示 一 个 包含 用 户 名 的 欢迎 消息 ， 并 提醒 用 户 需 要 进 
行 账户 确认 才能 获得 权限 。 为 此 ， 两 个 断言 语句 被 用 于 检查 响应 是 否 为 这 个 页 面 。 值 得 注 
意 的 一 点 是 ， 直 接 搜索 字符 串 "HeLLo， john!' 并 没有 用 ， 因 为 这 个 字符 串 由 动态 部 分 和 静 
态 部 分 组 成 ， 而 且 两 部 分 之 间 有 额外 的 空白 。 为 了 避免 测试 时 空白 引起 的 问题 ， 我 们 使 用 
更 为 灵活 的 正则 表达 式 。 


下 一 步 我 们 要 确认 账户 ， 这 里 也 有 一 个 小 障碍 。 在 广 册 过 程 中 ， 通 过 电子 邮件 将 确认 URL 















































发 给 用 户 ， 而 在 测试 中 处 理 电 子 邮件 不 是 一 件 简单 的 事 。 上 面 这 个 测试 使 用 的 解决 方法 名 
略 了 注册 时 生成 的 令 牌 ， 直 接 在 User 实例 上 调用 方法 重新 生成 一 个 新 令 牌 。 在 测试 环境 
中 ，Flask-Mail 会 保存 邮件 正文 ， 所 以 还 有 一 种 可 行 的 解决 方法 ， 即 通过 解析 邮件 正文 来 





提取 令 牌 。 











得 到 令 牌 后 ， 测 试 的 第 三 部 分 模拟 用 户 点 击 确认 令 牌 URL。 这 一 过 程 通过 向 确认 URL 发 
起 GET 请 求 并 附 上 确认 令 牌 来 完成 。 这 个 请 求 的 响应 是 重 定向 ， 转 到 首页 ， 但 这 里 再 次 指 
定 了 参数 follow_redirects=True， 所 以 测试 客户 端 会 自动 向 重 定向 的 页 面 发 起 请 求 。 此 
外 ， 还 要 检查 响应 中 是 否 包含 欢迎 消息 和 一 个 向 用 户 说 明确 认 成 功 的 Flash 消息 。 





这 个 测试 的 最 后 一 步 是 向 退 
搜索 一 个 Flash 消息 。 














15.2.2 ”测试 Web 肯 








路 由 发 送 GET 请 求 ， 为 了 证 实 成 功 退 出 ， 这 段 测 试 在 响应 中 


如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15b 签 出 程序 的 这 个 版 本 。 


及 务 


Flask 测试 客户 端 还 可 用 来 测试 REST Web 服务 。 示 例 15-5 是 一 个 单元 测试 示例 ， 包 含 了 


两 个 测试 。 


示例 15-5 tests/test_api.py: 


使 用 Flask 测试 客户 端 测试 REST API 


class APITestCase(Unittest.TestCase) : 


# ... 
def get api_ headers(self, username, password): 
return { 
'Authorization': 
'Basic ' + b64encode( 
(username + ':' + password).encode('utf-8')).decode('utf-8'), 
'Accept': 'application/json', 


'Content-Type': 'application/json’ 


} 


def test_no_auth(self): 
response = self.client.get(url_for('api.get_posts'), 


content_type='application/json') 


self.assertTrue(response.status_code == 401) 


def test posts(self): 


# 添加 一 个 用 户 


r = Role.query.filter_by(name='User').first() 
self.assertIsNotNone(r) 


U = User(email= 


'john@example.com', password='cat', confirmed=True, 


role=r) 
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db.session.add(u) 
db.session.commit() 


# 写 一 篇 文章 

response = self.client.post( 
url_for('api.new_post'), 
headers=self.get_auth_header('john@example.com', 'cat'), 
data=json.dumps({'body': 'body of the *blog* post'})) 


self.assertTrue(response.status_code == 201) 
url = response.headers.get('Location’') 


self.assertIsNotNone(url) 


# 获取 刚 发 布 的 文章 


response = self.client.get( 


headers=self.get_auth_header('john@example.com', 'cat')) 


self.assertTrue(response.status_code == 200) 

json_response = json.Loads(response.data.decode('utf-8')) 

seLf .assertTrue(json_response['urL'] == url) 

seLf .assertTrue(json_response['body'] == 'body of the *blog* post') 


seLf .assertTrue(json_response['body_htmL' ] == 


"<p>body of the <em>blog</em> post</p>') 


测试 API 时 使 用 的 setup() 和 tearDown() 方法 和 测试 普通 程序 所 用 的 一 样 ， 不 过 API 不 使 
用 cookie， 所 以 无 需 配 置 相应 支持 。get_api_headers() 是 一 个 辅助 方法 ， 返 回 所 有 请 求 都 
要 发 送 的 通用 首部 ， 其 中 包含 认证 密令 和 MIME 类 型 相关 的 首部 。 大 多 数 测 试 都 要 发 送 这 


些 首部 。 


test_no_auth() 是 一 个 简单 的 测试 ， 确 保 Web 服务 会 拒绝 没有 提供 认证 密令 的 请 求 ， 返 回 
401 错误 码 。test_posts() 测试 把 一 个 用 户 插入 数据 库 ， 然 后 使 用 基于 REST 的 API 创建 























一 篇 博客 文章 ， 然 后 再 读 取 这 篇 文章 。 所 有 请 求 主体 中 发 送 的 数据 都 要 使 用 json.dumps() 


方法 进行 编码 ， 


因为 Flask 测试 客户 端 不 会 





自动 编码 JSON 格式 数据 。 类 似 地 ， 返 回 的 响 








应 主体 也 是 JSON 格式 ， 处 理 之 前 必须 使 用 json. loads() 方法 解码 。 





15.3 ”使 用 Selenium 进 


Flask 测试 客户 端 不 








如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15c 签 出 程序 的 这 个 版 本 。 





ZX 一 sm 中- 
行 端 到 端 测试 
全 模拟 运行 中 的 程序 所 在 的 环境 。 例 如 ， 如 果 依 赖 运行 在 客户 端 


浏览 器 中 的 JavaScript 代码 ， 任 何 程序 都 无 法 正常 工作 ， 因 为 响应 发 给 测试 的 JavaScript 代 


码 无 法 像 在 真正 的 Web 浏 














客户 端 中 那样 运行 。 





如 果 测 试 需要 完整 的 环境 ， 除了 使 用 真正 的 Web 浏览 器 连接 Web 服务 器 中 运行 的 程序 外 ， 
别 无 他 选 。 幸 运 的 是 ， 大 多 数 浏 览 器 都 支持 自动 化 操作 。Selenium (http://www.seleniumhq. 
org/) 是 一 个 Web 浏览 器 自动 化 工具 ， 支 持 3 种 主要 操作 系统 中 的 大 多 数 主流 Web 浏览 器 。 
Selenium 的 Python 接口 使 用 pip 进行 安装 : 

(venv) $ pip install selenium 
使 用 Selenium 进行 的 测试 要 求 程序 在 Web 服务 器 中 和 运行， 监听 真实 的 HTTP 请 求 。 本 而 
于 用 的 方法 是 ， 让 程序 运行 在 后 台 线 程 里 的 开发 服务 器 中 ， 而 测试 运行 在 主线 程 中 。 在 测 
试 的 控制 下 ，Selenium 启动 Web 浏 览 器 并 连接 程序 以 执行 所 需 操 作 。 




















使 用 这 种 方法 要 解决 一 个 问题 ， 即 当 所 有 测试 都 完成 后 ， 要 停止 Flask 服务 器 ， 而 且 最 好 
使 用 一 种 优雅 的 方式 ， 以 便 代 码 履 盖 检 测 引 擎 等 后 台 作 业 能 够 顺利 完成 。Werkzeug Web 
服务 嚣 本身 就 有 停止 选项 ， 但 由 于 服务 器 运行 在 单独 的 线程 中 ， 关 闭 服务 器 的 唯一 方法 是 
发 送 一 个 普通 的 HITP 请 求 。 示 例 15-6 实现 了 关闭 服务 器 的 路 由 。 




















示例 15-6 ”app/main/views.py: 关闭 服务 器 的 路 由 
@main.route('/shutdown') 
def server_shutdown(): 
if not current_app.testing: 
abort(404) 
shutdown = request.environ.get('werkzeug.server.shutdown') 
if not shutdown: 
abort(500) 
shutdown() 
return 'Shutting down...' 


只 有 当 程 序 运行 在 测试 环境 中 时 ， 这 个 关闭 服务 器 的 路 由 才 可 用 ， 在 其 他 配置 中 调用 时 将 


不 起 作用 。 在 实际 过 程 中 ， 关 闭 服务 器 时 要 调用 Werkzeug 在 环境 中 提供 的 关闭 函数 。 调 
用 这 个 函数 且 请 求 处 理 完成 后 ， 开 发 服务 器 就 知道 自己 需要 优雅 地 退出 了 。 








示例 15-7 是 使 用 Selenium 运行 测试 时 测试 用 例 所 用 的 代码 结构 。 


示例 15-7 tests/test_selenium.py: 使 用 Selenium 运行 测试 的 框架 


from selenium import webdriver 


class SeleniumTestCase(unittest.TestCase): 
client = None 


@classmethod 
def setUpClass(cls): 
# 启动 Firefox 
try: 
cls.client = webdriver.Firefox() 
except: 
pass 
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# 如 果 无 法 启动 浏览 器 ， 则 跳 过 这 些 测试 

if cls.client: 
# 创建 程序 
cls.app = create_app('testing') 
cls.app_context = cls.app.app_context() 
cls.app_context.push() 


# 禁止 日 志 ， 保持 输出 简洁 

import logging 

Logger = logging.getLogger('werkzeug') 
Logger .setLevel("ERROR") 


# 创建 数据 库 ， 并 使 用 一 些 虚 拟 数 据 填充 
db.create_all() 

Role.insert_roles() 

User .generate fake(10) 
Post.generate_ fake(10) 




















# 添加 管理 员 
admin_role = Role.query.filter_by(permissions=Qxff).first() 
admin = User(email='john@example.com’', 
Username=' john' ，password='cat ' ， 
role=admin_role, confirmed=True) 
db.session.add(admin) 
db.session.commit() 


# 在 一 个 线程 中 启动 Flask 服务 器 
threading.Thread(target=cls.app.run).start() 


@classmethod 
def tearDownClass(cls): 
if cls.client: 


# 关闭 Flask 服务 器 和 浏览 器 
cls.client.get('http://Llocalhost:5000/shutdown') 
cls.client.close() 


# 销毁 数据 库 
db.drop_all() 
db.session.remove() 


# 删除 程序 上 下 文 
cls.app_context.pop() 


def setUp(self): 
if not self.client: 
self.skipTest('Web browser not available') 


def tearDown(self): 
pass 


setUpClass() 和 tearDownClass() 类 方法 分 别 在 这 个 类 中 的 全 部 测试 运行 前 、 后 执行 。 
setUpClass() 方法 使 用 Selenium 提供 的 webdriverAPI 启动 一 个 Firefox 实例 ， 并 创建 一 个 
程序 和 数据 库 ， 其 中 写 入 了 一 些 供 测 试 使 用 的 初始 数据 。 然 后 调用 标准 的 app.run() 方法 











在 一 个 线程 中 启动 程序 。 完 成 所 有 测试 后 ， 程 序 会 收 到 一 个 发 往 /shutdown 的 请 求 ， 进 而 
停止 后 台 线 程 。 随 后 ， 关 闭 浏览 器 ， 删 除 测 试 数据 库 。 





Selenium 支持 Firefox 之 外 的 很 多 Web 浏览 器 。 如 果 你 想 使 用 其 他 Web 浏 


1 和 DR. 


览 器 ， 请 查阅 Selenium 文档 (http://docs.seleniumhq.org/docs/) 。 























setUp() 方法 在 每 个 测试 运行 之 前 执行 ， 如 果 Selenium 无 法 利用 startUpCLass() 方法 启动 
Web 浏览 器 就 跳 过 测试 。 示 例 15-8 是 一 个 使 用 Selenium 进行 测试 的 例子 。 


示例 15-8 tests/test_selenium.py: Selenium 单元 测试 示例 


class SeleniumTestCase(unittest.TestCase): 
# ... 


def test admin home_page(self): 
# 进入 首页 
self.client.get('http://localhost:5000/') 
self.assertTrue(re.search('Hello,\s+Stranger!', 
self.client.page_source)) 


# 进入 登录 页 面 
self.client.find element by_link_ text('Log In').click() 
self.assertTrue('<h1i>Login</h1i>' in self.client.page_ source) 


# 登录 

self.client.find element_by_name('email').\ 
send_keys('john@example.com') 

self.client.find element by_name('password').send_ keys('cat') 

self.client.find element by_name('submit').click() 

self.assertTrue(re.search('Hello,\s+john!', self.client.page_source)) 


# 进入 用 户 个 人 资料 页 面 
self.client.find element_ by_link_text('Profile').click() 
self.assertTrue('<h1>john</h1i>' in self.client.page_ source) 


这 个 测试 使 用 setupClass() 方法 中 创建 的 管理 员 账户 登录 程序 ， 然 后 打开 资料 页 。 注 意 ， 
这 里 使 用 的 测试 方法 和 使 用 Flask 测试 客户 端 时 不 一 样 。 使 用 Selenium 进行 测试 时 ， 测 试 
向 Web 浏览 器 发 出 指令 且 从 不 直接 和 程序 交互 。 发 给 浏览 器 的 指令 和 真实 用 户 使 用 鼠标 或 
键盘 执行 的 操作 几乎 一 样 。 





这 个 测试 首先 调用 get() 方法 访问 程序 的 首页 。 在 浏览 器 中 ， 这 个 操作 就 是 在 地 址 栏 
中 输入 URL。 为 了 验证 这 一 步 操作 的 结果 ， 测 试 代码 检查 页 面 源码 中 是 否 包含 “Hello, 


Stranger!” 这 个 欢迎 消息 。 











为 了 访问 登录 页 面 ， 测 试 使 用 find_element_by_link_text() 方法 查找 “Log In” 链 接 ， 然 
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后 在 这 个 链接 上 调用 click() 方法 ， 从 而 在 浏览 器 中 触发 一 次 真正 的 点 击 。Selenium 提供 
了 很 多 find_element_by...() 简便 方法 ， 可 使 用 不 同 的 方式 搜索 元 素 。 


为 了 登录 程序 ， 测 试 使 用 find_element_by_name() 方法 通过 名 字 找 到 表单 中 的 电子 邮件 和 
密码 字段 ， 然 后 再 使 用 send_keys() 方法 在 各 字段 中 填 人 值 。 表 单 的 提交 通过 在 提交 按钮 
上 调用 click() 方法 完成 。 此 外 ， 还 要 检查 针对 用 户 定制 的 欢迎 消息 ， 以 确保 登录 成 功 且 
浏览 器 显示 的 是 首页 。 


测试 的 最 后 一 部 分 是 找到 导航 条 中 的 “Profile” 链 接 ， 然 后 点 击 。 为 证 实 资料 页 已 经 加 载 ， 
测试 要 在 页 面 源码 中 搜索 内 容 为 用 户 名 的 标题 。 














如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
15d 签 出 程序 的 这 个 版 本 。 这 次 更 新 包含 了 一 个 数据 库 迁 移 ， 所 以 签 出 代码 
后 记得 要 运行 python manage.py db upgrade。 为 保证 安装 了 所 有 依赖 ， 你 还 
要 运行 ptp install -r requirements/dev.txt。 








15.4 值得 测试 吗 


读 到 这 里 你 可 能 会 问 ， 为 了 测试 而 如 此 折腾 Flask 测试 客户 端 和 Selenium， 值 得 吗 ? 这 是 
一 个 合理 的 疑问 ， 不 过 不 容易 回答 。 


不 管 你 是 否 喜欢 ， 程 序 肯 定 要 做 测试 。 如 果 你 自己 不 做 测试 ， 用 户 就 要 充当 不 情愿 的 测试 
员 ， 用 户 发 现 问题 后 ， 你 就 要 项 着 压力 进行 修正 。 检 查 数据 库 模 型 和 其 他 无 需 在 程序 上 下 
文中 执行 的 代码 很 简单 ， 而 且 有 针对 性 ， 这 类 测试 一 定 要 做 ， 因 为 你 无 需 投 入 过 多 精力 就 
能 保证 程序 逻辑 的 核心 功能 可 以 正常 运行 。 




















我 们 有 时候 也 需要 使 用 Flask 测试 客户 端 和 Selenium 进行 端 到 端 形式 的 测试 ， 不 过 这 类 测 
试 编写 起 来 比较 复杂 ， 只 适用 于 无 法 进行 单独 测试 的 功能 。 程 序 代 码 应 该 进行 合理 组 织 ， 
尽量 把 业务 逻辑 写 入 数据 库 模 型 或 独立 于 程序 上 下 文 的 辅助 类 中 ， 这 样 测试 起 来 才 更 简 
单 。 视 图 函数 中 的 代码 应 该 保持 简洁 ， 仪 发 挥 粘 合 剂 的 作用 ， 收 到 请 求 后 调用 其 他 类 中 对 
应 的 操作 或 者 封装 程序 逻辑 的 函数 。 


因此 ， 测 试 绝对 值得 。 重 要 的 是 我 们 要 设计 一 个 高 效 的 测试 策略 ， 还 要 编写 能 合理 利用 这 
一 策略 的 代码 。 
































第 16 章 
性 能 








没 人 喜欢 使 用 运行 缓慢 的 程序 。 页 面 加载 时 间 太 长 会 让 用 户 失 去 兴趣 ， 所 以 尽早 发 现 并 修 
正 性 能 问题 是 一 件 很 重要 的 工作 。 在 本 章 ， 我 们 要 探讨 影响 性 能 的 两 个 重要 因素 。 


16.1 记录 影响 性 能 的 缓慢 数据 库 查询 

如 果 程 序 性 能 随 着 时 间 推 移 不 断 降低 ， 那 很 有 可 能 是 因为 数据 库 查 询 变 慢 了 ， 随 着 数据 库 
规模 的 增长 ， 这 一 情况 还 会 变 得 更 糟 。 优 化 数据 库 有 时 很 简单 ， 只 需 添 加 更 多 的 索引 即 
可 ; 有 了 时 却 很 复杂 ， 需 要 在 程序 和 数据 库 之 间 加 入 缓存 。 大 多 数 数据 库 查 询 语言 都 提供 了 
explain 语句 ， 用 来 显示 数据 库 执行 查询 时 采取 的 步 又。 从 这 些 步 骤 中 ， 我 们 经 常 能 发 现 
数据 库 或 索引 设计 的 不 足 之 处 。 


不 过 ， 在 开始 优化 查询 之 前 ， 我 们 必须 要 知道 哪些 查询 是 值得 优化 的 。 在 一 次 典型 请 求 
中 ， 可 能 要 执行 多 条 数据 库 查 询 ， 所 以 经 常 很 难 分 辩 哪 一 条 查询 较 慢 。EFlask-SQLAlchemy 
提供 了 一 个 选项 ， 可 以 记录 请 求 中 执行 的 与 数据 库 查 询 相关 的 统计 数字 。 在 示例 16-1 中 ， 
我 们 可 以 看 到 如 何 使 用 这 个 功能 把 慢 于 设 定 阔 值 的 查询 写 和 日志 。 























示例 16-1 app/main/views.py: 报告 缓慢 的 数据 库 查 询 


from flask.ext.sqlalchemy import get_debug_queries 


@main.after_app_request 
def after_request(response): 
for query in get debug_ queries(): 
if query.duration >= current_app.config['FLASKY_SLOW_DB_QUERY_TIME']: 
current_app. logger .warning( 
'Slow query: %s\nParameters: %s\nDuration: %fs\nContext: %s\n' % 
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(query.statement, query.parameters, query.duration, 
query.context)) 
return response 


这 个 功能 使 用 after_app_request 处 理 程 序 实现 ， 它 和 before_app_request 处 理 程序 的 工 
作 方 式 类 似 ， 只 不 过 在 视图 函数 处 理 完 请 求 之 后 执行 。Flask 把 响应 对 象 传 给 after_app_ 
request 处 理 程 序 ， 以 防 需 要 修改 响应 。 

















在 本 例 中 ，after_app_request 处 理 程序 没有 修改 响应 ， 只 是 获取 Flask-SQLAlchemy 记录 
的 查询 时 间 并 把 缓慢 的 查询 写 入 日 志 。 





get_debug_queries() 图 数 返回 一 个 列表 ， 其 元 素 是 请 求 中 执行 的 查询 。Flask-SQLAlchemy 
记录 的 查询 信息 如 表 16-1 所 示 。 





表 16-1 Flask-SQLAIchemy 记 录 的 查询 信息 
statement SQL 语句 
parameters SQL 语句 使 用 的 参数 
start_time 执行 查询 时 的 时 间 




















end_time 返回 查询 结果 时 的 时 间 
duration 查询 持续 的 时 间 ， 单 位 为 秒 








after_app_request 处 理 程序 遍历 get_debug_queries() 函数 获取 的 列表 ， 把 持续 时 间 比 设 
定 闪 值 长 的 查询 写 入 日 志 。 写 入 的 日 志 被 设 为 “警告 ”等 级 。 如 果 换 成 “错误 ”等 级 ， 发 
现 缓慢 的 查询 时 还 会 发 送 电子 邮件 。 





默认 情况 下 ，get_debug_queries() 国 数 只 在 调试 模式 中 可 用 。 但 是 数据 库 性 能 问题 很 少 发 
生 在 开发 阶段 ， 因 为 开发 过 程 中 使 用 的 数据 库 较 小 。 因 此 ， 在 生产 环境 中 使 用 该 选项 才能 
发 挥 作 用 。 若 想 在 生产 环境 中 分 析 数 据 库 性 能 ， 我 们 必须 修改 配置 ， 如 示例 16-2 所 示 。 





示例 16-2 ”config.py: 局 用 缓慢 查询 记录 功能 的 配置 
class Config: 
# ... 
SQLALCHEMY_RECORD_QUERIES = True 
FLASKY_DB_QUERY_TIMEOUT = 0.5 
# ... 


SQLALCHEMY_RECORD_QUERIES 告诉 Flask-SQLAlchemy 启用 记录 查询 统计 数字 的 功能 。 缓 慢 
查询 的 国 值 设 为 0.5 秒 。 这 两 个 配置 变量 都 在 Config 基 类 中 设置 ， 因 此 在 所 有 环境 中 都 可 
使 用 。 























每 当 发 现 缓慢 查询 ，Flask 程序 的 日 志 记录 器 就 会 写 人 一 条 记录 。 若 想 保存 这 些 日 志 记 录 ， 
必须 配置 日 志 记录 器 。 日 志 记录 器 的 配置 根据 程序 所 在 主机 使 用 的 平台 而 有 所 不 同 ， 第 17 
章 会 举 一 些 例子 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
16a 签 出 程序 的 这 个 版 本 。 








16.2 分 析 源 码 

性 能 问题 的 另 一 个 可 能 诱因 是 高 CPU 消耗 ， 由 执行 大 量 运算 的 函数 导致。 源码 分 析 器 能 
找 出 程序 中 执行 最 慢 的 部 分 。 分 析 器 监视 运行 中 的 程序 ， 记 录 调 用 的 函数 以 及 运行 各 函数 
所 消耗 的 时 间 ， 然 后 生成 一 份 详细 的 报告 ， 指 出 运行 最 慢 的 函数 。 





~ 








分 析 一 般 在 开发 环境 中 进行 。 源 码 分 析 器 会 让 程序 运行 得 更 慢 ， 因 为 分 析 器 
要 监视 并 记录 程序 中 发 生 的 一 切 。 因 此 我 们 不 建议 在 生产 环境 中 进行 分 析 ， 
除非 使 用 专 为 生产 环境 设计 的 轻 量 级 分 析 器 。 























Flask 使 用 的 开发 Web 服务 器 由 Werkzeug 提供 ， 可 根据 需要 为 每 条 请 求 启用 Python 分 析 
器 。 示 例 16-3 向 程序 中 添加 了 一 个 新 命令 ， 用 来 启动 分 析 器 。 





示例 16-3 manage.py: 在 请 求 分 析 器 的 监视 下 运行 程序 

@manager .command 

def profile(length=25, profile_dir=None): 
"""Start the application Under the code profiler.""" 
from werkzeug.contrib.profiler import ProfilerMiddleware 
app.wsgi_app = ProfilerMiddleware(app.wsgi_app, restrictions=[length], 

profile_dir=profile_dir) 

app.run() 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
16b 签 出 程序 的 这 个 版 本 。 











使 用 python manage.py profile 启动 程序 后 ， 终 端 会 显示 每 条 请 求 的 分 析 数 据 ， 其 中 包 
含 运 行 最 慢 的 25 个 国 数 。- -Length 选项 可 以 修改 报告 中 显示 的 函数 数量 。 如 果 指 定 了 








--profile-dir 选项 ， 每 条 请 求 的 分 析 数 据 就 会 保存 到 指定 目录 下 的 一 个 文件 中 。 分 析 器 
数据 文件 可 用 来 生成 更 详细 的 报告 ， 例 如 调用 图 。Python 分 析 器 的 详细 信息 请 参阅 官方 文 
档 (https:Wdocs.python.org/2/library/profile.html ) 。 


现在 我 们 完成 了 部 署 前 的 准备 工作 。 在 下 一 竟 ， 你 会 了 解 部 署 程序 的 大 致 过 程 。 
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部 着 





Flask 自 带 的 开发 Web 服务 器 不 够 强健 、 安 全 和 高 效 ， 无 法 在 生产 环境 中 使 用 。 在 本 章 ， 
我 们 要 介绍 几 种 不 同 的 部 署 方 式 。 


17.1 部 署 流 程 
不 管 使 用 哪 种 托管 方案 ， 程 序 安装 到 生产 服务 器 上 之 后 ， 都 要 执行 一 系列 的 任务 。 最 好 的 
例子 就 是 创建 或 更 新 数据 库 表 。 


如 果 每 次 安装 或 升级 程序 都 手动 执行 任务 ， 那 么 容易 出 错 也 浪费 时 间 ， 所 以 我 们 可 以 在 
manage.py 中 添加 一 个 命令 ， 自 动 执行 所 需 操 作 。 














示例 17-1 实现 了 一 个 适用 于 Flasky 的 deploy 命令 。 


示例 17-1 manage.py: 部 署 命令 
@manager .command 
def deploy(): 
"""Run deployment tasks.""" 
from flask.ext.migrate import upgrade 
from app.models import Role, User 


# 把 数据 库 迁 移 到 最 新 修订 版 本 
upgrade() 


# 创建 用 户 角 色 


Role.insert_roles() 
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# 让 所 有 用 户 都 关注 此 用 户 
User.add_self_follows() 











这 个 命令 调用 的 函数 之 前 都 已 经 定义 好 了 ， 现 在 只 是 将 它们 集中 调用 。 





如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
17a 签 出 程序 的 这 个 版 本 。 








定义 这 些 函 数 时 考虑 到 了 多 次 执行 的 情况 ， 所 以 即使 多 次 执行 也 不 会 产生 问题 。 因 此 每 次 
安装 或 升级 程序 时 只 需 运行 deploy 命令 就 能 完成 所 有 操作 。 


17.2 ”把 生产 环境 中 的 错误 写 入 日 志 


如 果 调 试 模式 中 运行 的 程序 发 生 错误 ， 那 么 会 出 现 Werkzeug 中 的 交互 式 调试 器 。 网 页 中 
显示 错误 的 栈 跟 踪 ， 而 且 可 以 查看 源码 ， 其 至 还 能 使 用 Flask 的 网 页 版 交互 调试 器 在 每 个 
栈 帧 的 上 下 文中 执行 表达 式 。 








调试 器 是 开发 过 程 中 进行 问题 调试 的 优秀 工具 ， 但 其 显然 不 能 在 生产 环境 中 使 用 。 生 产 环 
并 中 发 生 的 错误 会 被 静默 掉 ， 取 而 代 之 的 是 向 用 户 显示 一 个 500 错误 页 面 。 不 过 幸好 错误 
的 栈 跟 踪 不 会 完全 丢失 ， 因 为 Flask 会 将 其 写 入 日 志文 件 。 




















在 程序 启动 过 程 中 ，Flask 会 创建 一 个 Python 提供 的 logging.Logger 类 实例 ， 并 将 其 附属 
到 程序 实例 上 ， 得 到 app.togger。 在 调试 模式 中 ， 日 志 记 录 器 会 把 记录 写 入 终端 ， 但 在 生 
产 模式 中 ， 默 认 情况 下 没有 配置 日 志 的 处 理 程序 ， 所 以 如 果 不 添 加 处 理 程序 ， 就 不 会 保存 
上 日志。 示例 17-2 中 的 改动 配置 了 一 个 日 志 处 理 程序 ， 把 生产 模式 中 出 现 的 错误 通过 电子 邮 
件 发 送 给 FLASKY_ADMIN 中 设置 的 管理 员 。 






































示例 17-2 ”config.py: 程序 出 错时 发 送 电子 邮件 
class ProductionConfig(Config): 
# ... 
@classmethod 
def init_app(cls, app): 
Config.init_app(app) 


# 把 错误 通过 电子 邮件 发 送 给 管理 员 

import Logging 

from logging.handlers import SMTPHandler 

credentials = None 

secure = None 

if getattr(cls, 'MAIL_USERNAME', None) is not None: 
credentials = (cls.MAIL_USERNAME, cls.MAIL_PASSWORD) 
if getattr(cls, 'MAIL_USE_TLS', None): 























secure = () 
mail_handler = SMTPHandler( 
mailhost=(cls.MAIL_SERVER, cls.MAIL_PORT), 
fromaddr=cls.FLASKY_MAIL_SENDER, 
toaddrs=[cls.FLASKY_ADMIN], 
subject=cls .FLASKY_MAIL_SUBJECT_PREFIX + ' Application Error', 
credentials=credentials, 
secure=secure) 
mail_handler .setLevel(logging.ERROR) 
app. Logger .addHandler(mail_handler) 


回顾 一 下 ， 所 有 配置 实例 都 有 一 个 init_app() 静态 方法 ， 在 create_app() 方法 中 调用 。 在 
ProductionConfig 类 的 init_app() 方法 的 实现 中 ， 配 置 程序 的 日 志 记 录 器 把 错误 写 入 电子 
邮件 日 志 记 录 器 。 


电子 邮件 日 志 记 录 器 的 日 志 等 级 被 设 为 logging.ERROR， 所 以 只 有 发 生 严 重 错误 时 才 会 发 送 
电子 邮件 。 通 过 添加 适当 的 日 志 处 理 程序 ， 可 以 把 较 轻 缓 等 级 的 日 志 消息 写 人 文件 、 系 统 
日 志 或 其 他 的 支持 方法 。 这 些 日 志 消 息 的 处 理 方法 很 大 程度 上 依赖 于 程序 使 用 的 托管 平台 。 














如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
17b 签 出 程序 的 这 个 版 本 。 


是 











17.3 云 部 署 


程序 托管 的 最 新 潮流 是 托管 到 云端 。 云 技术 以 前 称 为 平台 即 服务 (Platform as a Service， 
PaaS)， 它 让 程序 开发 者 从 安装 和 维护 运行 程序 的 软 硬 件 平 台 的 日 常 工作 中 解放 出 来 。 在 
PaaS 模型 中 ， 服 务 提供 商 完全 接管 了 运行 程序 的 平台 。 程 序 开发 者 使 用 服务 商 提供 的 工 
有 具 和 库 把 程序 集成 到 平台 上 ， 然 后 将 其 上 传 到 提供 商 维护 的 服务 器 中 ， 部 署 的 过 程 往 往 只 
需 几 秒 钟 。 大 多 数 PaaS 提供 商都 可 以 通过 按 需 添加 或 删除 服务 器 以 实现 程序 的 动态 扩展 ， 
从 而 满足 不 同 请 求 量 的 需求 。 

云 部 署 有 较 高 的 灵活 性 ， 而 且 使 用 起 来 相对 容易 。 当 然 ， 这 些 优势 都 是 花 钱 买 来 的 。 


Heroku 是 最 流行 的 Paas 提供 商 之 一 ， 对 Python 支持 良好 。 下 一 节 ， 我 们 将 详细 说 明 如 何 
把 程序 部 署 到 Heroku 中 。 





















































17.4 Heroku 平 台 


Heroku 是 最 早出 现 的 PaaS 提供 商 之 一 ， 从 2007 年 就 开始 运营 。Heroku 平台 的 灵活 性 极 
高 且 支 持 多 种 编程 语言 。 若 想 把 程序 部 团 到 Heroku 上 ， 开 发 者 要 使 用 Git 把 程序 推送 到 
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Heroku 的 Git 服务 器 上 。 在 服务 器 上 ，git push 命令 会 自动 触发 安装 、 配 置 和 部 署 程序 。 


Heroku 使 用 名 为 Dyno 的 计算 单元 衡量 用 量 ， 并 以 此 为 依据 收取 服务 费用 。 最 常用 的 Dyno 
类 型 是 Web Dyno， 表 示 一 个 Web 服务 器 实例 。 程 序 可 以 通过 使 用 更 多 的 Web Dyno 以 增强 
其 请 求 处 理 能 力 。 另 一 种 Dyno 类 型 是 Worker Dyno， 用 来 执行 后 台 作 业 或 其 他 辅助 任务 。 








Heroku 提供 了 大 量 的 插件 和 扩展 ， 可 用 于 数据 库 、 电 子 邮件 支持 和 其 他 很 多 服务 。 下 面 各 
节 将 展开 说 明 把 Flasky 部 署 到 Heroku 上 的 细节 步 又。 











17.4.1 准备 程序 

若 想 使 用 Heroku， 程 序 必须 托管 在 Git 仓 库 中 。 如 果 你 的 程序 托管 在 像 GitHub 或 
BitBucket 这 样 的 远程 Git 服务 器 上 ， 那 么 克隆 程序 后 会 创建 一 个 本 地 Git 仓库 ， 可 无 颖 用 
于 Heroku。 如 果 你 的 程序 没有 托管 在 Git 仓库 中 ， 那 么 必须 在 开发 电脑 上 创建 一 个 仓库 。 





























如 果 你 计划 把 程序 托管 在 Heroku 上 ， 最 好 从 开发 伊始 就 使 用 Git。GitHub 的 
帮助 指南 (http://help.github.com/) 中 有 针对 3 种 主流 操作 系统 的 安装 及 设置 
说 明 。 














1. 注册 Heroku 账 户 
在 使 用 Heroku 提供 的 服务 之 前 ， 你 必须 要 注册 一 个 账户 (http://heroku.com/)。 注 册 后 ， 你 
可 以 选择 免费 的 最 低 等 级 的 服务 托管 程序 ， 因 此 ，Heroku 非常 适合 做 实验 。 





2. 安装 Heroku Toolbelt 
最 方便 的 Heroku 程序 管理 方法 是 使 用 Heroku Toolbelt (https://toolbelt.heroku.com/) 命令 
行 工 具 。Toolbelt 由 两 个 Heroku 程序 组 成 。 





。 heroku: Heroku 客户 端 ， 用 来 创建 和 管理 程序 。 
。 forenan: 一 种 工具 ， 测 试 时 可 用 于 在 自己 的 电脑 上 模拟 Heroku 环境 。 





注意 ， 如 果 你 之 前 没有 安装 Git 客户 端 ， 那 么 Toolbelt 安装 程序 会 为 你 安装 Git。 


在 Heroku 客户 端 连接 服务 器 之 前 ， 你 需要 提供 Heroku 账户 密令 。heroku login 命令 可 以 
a 
完成 这 一 操作 : 


$ heroku login 

Enter your Heroku credentials. 

Email: <your-email-address> 

Password (typing will be hidden): <your-password> 
Uploading ssh public key .../id_rsa.pub 





把 你 的 SSH 公 钥 上 传 到 Heroku 这 一 点 很 重要 ， 上 传 后 才能 使 用 git push 命 
令 。 正 常情 况 下 ，login 命令 会 自动 创建 并 上 传 SSH 公 钥 。 但 你 也 可 以 使 用 
heroku keys:add 命令 单独 上 传 公 钥 或 者 上 传 额外 所 需 的 公 钥 。 





3. 创建 程序 
接 下 来 ， 我 们 要 使 用 Heroku 客户 端 创建 一 个 程序 。 为 此 ， 我 们 首先 要 确保 程序 已 纳入 Git 
源码 控制 系统 ， 然 后 在 顶级 目录 中 运行 如 下 命令 : 





$ heroku create <appname> 

Creating <appname>... done, stack is cedar 
http://<appname>.herokuapp.com/ | git@herokuy.com:<appname>.git 
Git remote heroku added 





Heroku 中 的 程序 名 必须 是 唯一 的 ， 所 以 你 要 找 一 个 没 被 其 他 程序 使 用 的 名 字 。 如 create 
命令 的 输出 所 示 ， 部 署 后 程序 可 通过 http://<appname>.herokuapp.com 访问 。 你 可 以 给 程序 
设置 自 定义 域名 。 











在 程序 创建 过 程 中 ，Heroku 还 给 你 分 配 了 一 个 Git 服务 器 ， 地 址 为 git@heroku.com: 
<appname>.git。create 命令 调用 git remote 命令 把 这 个 地 址 添加 为 本 地 Git 仓库 的 远程 服 
务 器 ， 名 为 heroku。 


4. 配置 数据 库 
Heroku 以 扩展 形式 支持 Postgres 数据 库 。 少 于 1 万 条 记录 的 小 型 数据 库 无 需 付 费 即 可 添加 
到 程序 中 : 





$ heroku addons:add heroku-postgresqL:dev 
Adding heroku-postgresqL:dev on <appname>... done, v3 (free) 
Attached as HEROKU_POSTGRESQL_BROWN_URL 
Database has been created and is available 
! This database is empty. If upgrading, yoyu can transfer 
! data from another database with pgbackups:restore. 
Use heroku addons:docs heroku-postgresqL:dev to view documentation. 


环境 变量 HEROKU_POSTGRESQL_BROWN_URL 中 保存 了 数据 库 的 URL。 注 意 ， 运 行 这 个 命令 
后 ， 你 得 到 的 颜色 可 能 不 是 棕色 。Heroku 中 的 每 个 程序 都 支持 多 个 数据 库 ， 而 每 个 数据 库 
URL 中 的 颜色 都 不 一 样 。 数 据 库 的 地 位 可 以 提升 ， 把 URL 保存 到 环境 变量 DATABASE_URL 
中 。 下 述 命令 把 前 面 创建 的 棕色 数据 库 提升 为 主 数据 库 : 








$ heroku pg:promote HEROKU_POSTGRESQL_BROWN_URL 
Promoting HEROKU_POSTGRESQL_ BROWN_URL to DATABASE_URL... done 





DATABASE_URL 环境 变量 的 格式 正 是 SQLAlchemy 所 需 的 。 回 想 一 下 config.py 脚本 的 内 容 ， 如 果 
设 定 了 DATABASE_URL， 就 使 用 其 中 保存 的 值 ， 所 以 现在 程序 可 以 自动 连接 到 Postgres 数据 库 。 
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5. 配置 日 志 
之 前 我 们 实现 了 通过 电子 邮件 发 送 重 大 错误 消息 的 功能 ， 除 此 之 外 ， 配 置 其 他 轻 缓 等 级 的 
消息 也 尤为 重要 。 其 中 一 个 很 好 的 例子 是 第 16 章 添加 的 数据 库 缓 慢 查 询 警 告 消 息 。 


在 Heroku 中 , 日 志 必 须 写 入 stdout 或 stderr。Heroku 会 捕获 输出 的 日 志 ， 可 以 在 Heroku 
客户 端 中 使 用 heroku logs 命令 查看 。 


志 的 配置 可 添加 到 productionConfig 类 的 intt_app() 静态 方法 中 ， 但 由 于 这 种 日 志 处 
， Heroku 专用 的 ， 因 此 可 专门 为 这 个 平台 新 建 一 个 配置 类 ， 把 productionConfig 
作为 不 同类 型 生产 平台 的 基 类 。HerokuConfig 类 如 示例 17-3 所 示 。 





示例 17-3 ”config.py: Heroku 的 配置 


class HerokuConfig(ProductionConfig): 
@classmethod 
def init app(cls, app): 
ProductionConfig.init_app(app) 


# 输出 到 stderr 

import logging 

from logging import StreamHandler 
file_ handler = StreamHandler() 
file_handler.setLevel(logging.WARNING) 
app. Logger .addHandler (file_handler) 








通过 Heroku 执行 程序 时 ， 程 序 需 要 知道 要 使 用 的 就 是 这 个 配置 。manage.py 脚本 创建 的 程 
序 实例 通过 环境 变量 FLASK_CONFIG 决定 使 用 哪个 配置 ， 所 以 我 们 要 在 Heroku 的 环境 中 设 
定 这 个 变量 。 环 境 变量 使 用 Heroku 客户 端 中 的 config:set 命令 设 定 : 





$ heroku config:set FLASK_CONFIG=heroku 
Setting config vars and restarting <appname>... done, v4 
FLASK_CONFIG: heroku 


6. 配置 电子 邮件 

Heroku 没有 提供 SMTP 服务 器 ， 所 以 我 们 要 配置 一 个 外 部 服务 器 。 很 多 第 三 方 扩 展 能 把 
适用 于 生产 环境 的 邮件 发 送 服务 集成 到 Heroku 中 ,但 对 于 测试 和 评估 而 言 ， 使 用 继承 自 
Config 基 类 的 Gmail 配置 已 经 足够 了 。 


由 于 直接 把 安全 密令 写 入 脚本 存在 安全 隐患 ， 所 以 我 们 把 访问 Gmail SMTP 服务 器 的 用 户 
名 和 密码 保存 在 环境 变量 中 





$ heroku config:set MAIL_USERNAME=<your-gmail-username> 
$ heroku config:set MAIL_PASSWORD=<your-gmail-password> 


7. 运行 生产 Web 服 务 器 
Heroku 没有 为 托管 程序 提供 Web 服务 器 ， 相 反 ， 它 希望 程序 启动 自己 的 服务 器 并 监听 环 
境 变 量 PORT 中 设 定 的 端口 。 
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Flask 自 带 的 开发 Web 服务 器 表现 很 差 ， 因 为 它 不 是 为 生产 环境 设计 的 服务 器 。 有 两 个 
可 以 在 生产 环境 中 使 用 、 性 能 良好 且 支 持 Flask 程序 的 服务 器 ， 分 别 是 Gunicorn (http:// 
gunicorn.org/) 和 uWSGI (http://uwsgi-docs.readthedocs.org/en/latest/) 。 








若 想 在 本 地 测试 Heroku 配置 ， 我 们 最 好 在 虚拟 环境 中 安装 Web 服务 器 。 例 如 ， 可 通过 如 
下 命令 安装 Gunicorn : 


(venv) $ pip install gunicorn 





若 要 使 用 Gunicorn 运行 程序 ， 可 执行 下 面 的 命令 : 














(venv) $ gunicorn manage:app 

2013-12-03 09:52:10 [14363] [INFO] Starting gunicorn 18.0 

2013-12-03 09:52:10 [14363] [INFO] Listening at: http://127.0.0.1:8000 (14363) 
2013-12-03 09:52:10 [14363] [INFO] Using worker: sync 

2013-12-03 09:52:10 [14368] [INFO] Booting worker with pid: 14368 


manage:app 参数 冒号 左边 的 部 分 表示 定义 程序 的 包 或 者 模块 ， 冒 号 右边 的 部 分 表示 包 中 程 
序 实例 的 名 字 。 注 意 ，Gunicor 默认 使 用 端口 8000， 而 Flask 默认 使 用 5000。 


8. 添加 依赖 需求 文件 
Heroku 从 程序 顶级 文件 夹 下 的 requirements.txt 文件 中 加 载 包 依赖 。 这 个 文件 中 的 所 有 依赖 
都 会 在 部 署 过 程 中 导入 Heroku 创建 的 虚拟 环境 。 


Heroku 的 需求 文件 必须 包含 程序 在 生产 环境 中 使 用 的 所 有 通用 依赖 ， 以 及 支持 Postgres 数 
据 库 的 psycopg2 包 和 Gunicorn Web 服务 器 。 


示例 17-4 是 一 个 需求 文件 的 例子 。 

















示例 17-4 ”requirements.txt: Heroku 需求 文件 
-rT requirements/prod.txt 
gunicorn==18.0 
psycopg2==2.5.1 
9. 添加 Procfile 文 件 
Heroku 需要 知道 使 用 哪个 命令 启动 程序 。 这 个 命令 在 一 个 名 为 Procfile 的 特殊 文件 中 指定 。 
这 个 文件 必须 放 在 程序 的 顶级 文件 夹 中 。 


示例 17-5 展示 了 这 个 文件 的 内 容 。 


示例 17-5 ”Procfile: Heroku Procfile 文件 


web: gunicorn manage:app 











Procfile 文件 内 容 的 格式 很 简单 :在 每 一 行 中 指定 一 个 任务 名 ， 后 跟 一 个 冒号 ， 然 后 是 运行 
这 个 任务 的 命令 。 名 为 web 的 任务 比较 特殊 任务 ，Heroku 使 用 这 个 任务 启动 Web 服务 器 。 
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Heroku 会 为 这 个 任务 提供 一 个 PORT 环境 变量 ， 用 于 设 定 程序 监听 请 求 的 端口 。 如 果 设 定 
了 PORT 变量 ，Gunicorn 默认 就 会 使 用 其 中 保存 的 值 ， 因 此 无 需 将 其 包含 在 启动 命令 中 。 




















程序 可 在 Procfile 中 使 用 web 之 外 的 名 字 声 明 其 他 任务 ， 例 如 程序 所 需 的 其 
也 服务 。 部 署 程序 后 ，Heroku 会 运行 Procfile 中 列 出 的 所 有 任务 。 








区 





17.4.2 ”使 用 Foreman 进 行 测试 


Heroku Toolbelt 中 还 包含 另 一 个 名 为 Foreman 的 工具 ， 它 用 于 在 本 地 通过 Procfile 运行 程 
序 以 进行 测试 。Heroku 客户 端 设 定 的 像 FLASK_CONFIG 这 样 的 环境 变量 只 在 Heroku 服务 器 
上 可 用 ， 因 此 要 在 本 地 设 定 ， 这 样 Foreman 使 用 的 测试 环境 才 和 生产 环境 类 似 。Foreman 
会 在 程序 顶级 目录 中 搜寻 一 个 名 为 .env 的 文件 ， 加 载 其 中 的 环境 变量 。 例 如 .env 文件 中 可 
包含 以 下 变量 : 
































FLASK_CONFIG=heroku 
MAIL_USERNAME=<your -username> 
MAIL_PASSWORD=<your -password> 











由 于 .env 文件 中 包含 密码 和 其 他 敏感 的 账户 信息 ， 所 以 决 不 能 将 其 添加 到 
Git 仓库 中 。 


Foreman 有 多 个 命令 ， 其 中 两 个 主要 命令 是 foreman run 和 foreman start。run 命令 用 于 
在 程序 的 环境 中 运行 任意 命令 ， 特 别 适合 运行 创建 程序 数据 库 的 deploy 命令 : 





(venv) $ foreman run python manage.py deploy 
start 命令 读 取 Procfile 的 内 容 ， 执 行 其 中 的 所 有 任务 : 


(venv) $ foreman start 

22:55:08 web.1 started with pid 4246 

22:55:08 web.1 | 2013-12-03 22:55:08 [4249] [INFO] Starting gunicorn 18.0 
22:55:08 web.1 2013-12-03 22:55:08 [4249] [INFO] Listening at: http://... 
22:55:08 web.1 2013-12-03 22:55:08 [4249] [INFO] Using worker: sync 

22:55:08 web.1 2013-12-03 22:55:08 [4254] [INFO] Booting worker with pid: 4254 





Foreman 把 所 有 启动 任务 的 日 志 输 出 整合 在 一 起 并 转 储 至 终端 ， 其 中 每 一 行 的 前 面 都 加 入 
了 时 间 惟 和 任务 名 。 














使 用 -< 选项 还 能 模拟 多 个 Dyno。 例 如 ， 下 述 命令 启动 了 3 个 Web 工作 线程 (Web 





worker)， 各 职 程 分 别 监听 不 同 的 端口 : 


(venv) $ foreman start -c web=3 


17.4.3 ”使 用 Flask-SSLify 启 用 安全 HTTP 
用 户 登 录 程序 时 要 在 Web 表单 中 提交 用 户 名 和 密码 ， 这 些 数据 在 传输 过 程 中 可 被 第 三 方 截 
取 ， 就 像 前 文 已 多 次 提 及 的 。 为 了 避免 他 人 使 用 这 种 方式 偷 取 用 户 密令 ， 我 们 必须 使 用 安 
全 HITP， 使 用 公 钥 加 密 法 加 密 客户 端 和 服务 器 之 间 传 输 的 数据 。 


Heroku 上 的 程序 在 herokuapp.com 域 中 可 使 用 http:/ 和 https:/ 访问 ， 无 需 任何 配置 即 可 
直接 使 用 Heroku 的 SSL 证 书 。 唯 一 需要 做 的 是 让 程序 拦截 发 往 http:// 的 请 求 ， 重 定向 到 
https://， 这 一 操作 可 使 用 Flask-SSLify 扩展 完成 。 





我 们 要 将 Flask-SSLify 扩展 添加 到 requirements.txt 文件 中 。 示 例 17-6 中 的 代码 用 于 激活 这 
个 扩展 。 


示例 17-6 app/_init_.py: 把 所 有 请 求 重 定向 到 安全 HTTP 
def create_app(config_name) : 
# ... 
if not app.debug and not app.testing and not app.config['SSL_DISABLE']: 
from flask.ext.sslify import SSLify 
sslify = SSLify(app) 
# ... 


对 SSL 的 支持 只 需 在 生产 模式 中 启用 ， 而 且 所 在 平台 必须 支持 。 为 了 便于 打开 和 关闭 SSL， 


添加 了 一 个 名 为 SSL_DISABLE 的 新 配置 变量 。Config 基 类 将 其 设 为 True， 即 默认 情况 下 不 
使 用 SSL， 并 且 HerokuConfig 类 覆盖 了 这 个 值 。 这 个 变量 的 配置 方式 如 示例 17-7 所 示 。 




















示例 17-7 config.py: 配置 是 否 使 用 SSL 
class Config: 
# ... 
SSL_DISABLE = True 


class HerokuConfig(ProductionConfig): 
# ... 
SSL_DISABLE = bool(os.environ.get('SSL DISABLE')) 

















在 HerokuConfig 类 中 ，SSL_DISABLE 的 值 从 同名 环境 变量 中 读 取 。 如 果 这 个 环境 变量 的 值 
不 是 空 字 符 串 ， 那 么 将 其 转换 成 布尔 值 后 会 得 到 True， 即 禁用 SSL。 如 果 没 有 设 定 这 个 环 
并 变 量 或 者 其 值 为 空 字符 串 ， 转 换 成 布尔 值 后 会 得 到 Fatse。 为 了 避免 使 用 Foreman 时 启 
用 SSL， 必 须 在 .env 文件 中 加 入 SSL_DISABLE=1。 

















做 了 以 上 改动 后 ， 用 户 会 被 强制 使 用 SSL。 但 还 有 一 个 细节 需要 处 理 才 能 完善 这 一 功能 。 
使 用 Heroku 时 ， 客 户 端 不 直接 连接 托管 的 程序 ， 而 是 连接 一 个 反 向 代理 服务 器 ， 然 后 下 











二 中 
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把 请 求 重 定向 到 程序 上 。 在 这 种 连接 方式 中 ， 只 有 代理 服务 器 运行 在 SSL 模式 中 。 程 序 从 
代理 服务 器 接收 到 的 请 求 都 没有 使 用 SSL， 因 为 在 Heroku 网 络 内 部 无 需 使 用 高 安全 性 的 
请 求 。 程 序 生成 绝对 URL 时 ， 要 和 请 求 使 用 的 安全 连接 一 致 ， 这 时 就 产生 问题 了 ， 因 为 
使 用 反 向 代理 服务 器 时 ，request.is_secure 的 值 一 直 是 False。 














这 个 问题 会 在 生成 头像 的 URL 时 发 生 。 回 想 一 下 第 10 章 的 内 容 ，User 模型 中 的 
gravatar() 方法 在 生成 Gravatar URL 时 检查 了 request.is_secure， 根据 其 值 的 不 同 分 别 生 
成 安全 或 不 安全 的 URL。 如 果 通 过 SSL 请 求 页 面 ， 生 成 的 却 是 不 安全 的 头像 URL， 某 些 浏 
览 器 会 向 用 户 显示 安全 警告 ， 所 以 同一 页 面 中 的 所 有 内 容 都 要 使 用 安全 性 相同 的 URL。 









































代理 服务 器 通过 自 定义 的 HTTP 首部 把 客户 端 发 起 的 原始 请 求 信息 传 给 重 定向 后 的 Web 服 
务 器 ， 所 以 查看 这 些 首部 就 有 可 能 知道 用 户 和 程序 通信 时 是 否 使 用 了 SSL。Werkzeug 提 
供 了 一 个 WSGI 中 间 件 ， 可 用 来 检查 代理 服务 器 发 出 的 自 定义 首部 并 对 请 求 对 象 进行 相应 
更 新 。 例 如 ， 修 改 后 的 request.is_secure 表示 客户 端 发 给 反问 代理 服务 器 的 请 求 安 全 性 ， 
而 不 是 代理 服务 器 发 给 程序 的 请 求 安 全 性 。 示 例 17-8 展示 了 如 何 把 ProxyFix 中 间 件 添加 
到 程序 中 。 





























示例 17-8 ”config.py: 支持 代理 服务 器 
class HerokuConfig(ProductionConfig): 
# ... 
@classmethod 
def init app(cls, app): 
# ... 


# 处 理 代理 服务 器 首部 
from werkzeug.contrib.fixers import ProxyFix 
app.wsgi_app = ProxyFix(app.wsgi_app) 

















ProxyFix 中 间 件 添加 在 Heroku 配置 的 初始 化 方法 中 。 添 加 ProxyFix 等 WSGI 中 间 件 的 方 
法 是 包装 WSGI 程序 。 收 到 请 求 时 ， 中 间 件 有 机 会 审查 环境 ， 在 处 理 请 求 之 前 做 些 修改 。 
不 仅 Heroku 需要 使 用 ProxyFix 中 间 件 ， 任 何 使 用 反 向 代理 的 部 署 环境 都 需要 。 














如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
17c 签 出 程序 的 这 个 版 本 。 为 保证 安装 了 所 有 依赖 ， 你 还 要 运行 pip install 


-Fr requtrements .txt。 





17.4.4 执行 git push 命令 部 署 
部 署 过 程 的 最 后 一 步 是 把 程序 上 传 到 Heroku 服务 器 。 在 此 之 前 ， 你 要 确保 所 有 改动 都 已 
经 提交 到 本 地 Git 仓库 ， 然 后 执行 git push heroku master 把 程序 上 传 到 远程 仓库 heroku， 














$ git push heroku master 

Counting objects: 645, done. 

Delta compression using up to 8 threads. 
Compressing objects: 100% (315/315), done. 
Writing objects: 100% (645/645), 95.52 KiB, done. 
Total 645 (delta 369), reused 457 (delta 288) 


.---> Python app detected 
.----> No runtime.txt provided; assuming python-2.7.4. 
.----> Preparing Python runtime (python-2.7.4) 


----- > Compiled slug size: 32.8MB 
总 六 > Launching... done, v8 
http://<appname>.herokuapp.com deployed to Heroku 


To git@herokuyu.com:<appname>.git 
* [new branch] master -> master 


现在 ， 程 序 已 经 部 署 好 正在 运行 了 ， 但 还 不 能 正常 使 用 ， 因 为 还 没 执 行 deploy 命令 
Heroku 客户 端 可 按照 下 面 的 方式 执行 这 个 命令 : 





$ heroku run python manage.py deploy 

Running “python manage.py predepLoy ”attached to terminal... up, run.8449 
INFO [alembic.migration] Context impl PostgresqlImpl. 

INFO [alembic.migration] Will assume transactional DDL. 


I 


创建 并 配置 好 数据 库 表 之 后 就 可 以 重启 程序 了 ， 直 接 使 用 下 述 命令 即 可 : 





$ heroku restart 
Restarting dynos... done 


至 此 ， 程 序 就 完全 部 署 好 了 ， 可 通过 https://<appname>.hero-kuapp.com 访问 。 





17.4.5 ”查看 日 志 
程序 生成 的 日 志 输 出 会 被 Heroku 捕获 ， 若 想 查 看 日 志 内 容 ， 可 使 用 Logs 命令 : 





$ heroku Logs 





在 测试 过 程 中 ， 还 可 以 使 用 下 述 命 令 方 便 地 跟踪 日 志文 件 的 内 容 : 


$ heroku logs -t 


17.4.6 部署 一 次 升级 
升级 Heroku 程序 时 要 重复 上 述 步 又 。 所 有 改动 都 提交 到 Git 仓库 之 后 ， 可 执行 下 述 命令 进 
行 升级 : 





$ heroku maintenance:on 

$ git push heroku master 

$ heroku run python manage.py deploy 
$ heroku restart 

$ heroku maintenance:off 


Heroku 客户 端 提供 的 maintenance 命令 会 在 升级 过 程 中 下 线程 序 ， 并 向 用 户 显示 一 个 静态 
页 面 ， 告 知 网 站 很 快 就 能 恢复 。 


17.5 ”传统 的 托管 


如 果 你 选择 使 用 传统 托管 ， 那 么 要 购买 或 租用 服务 器 (物理 服务 器 或 虚拟 服务 器 )， 然 后 
自己 动手 在 服务 器 上 设置 所 有 需要 的 组 件 。 传 统 托管 一 般 比 托管 在 云 中 要 便宜 ， 但 显然 要 
付出 更 多 的 劳动 。 下 面 各 节 将 简要 说 明 其 中 涉及 的 工作 。 



































17.5.1 架设 服务 器 
在 能 够 托管 程序 之 前 ， 服 务 器 必须 完成 多 项 管理 任务 。 


。 安装 数据 库 服 务 器 ， 例 如 MySQL 或 Postgres。 也 可 使 用 SQLite 数据 库 ， 但 由 于 其 自身 
的 种 种 限制 ， 不 建议 用 于 生产 服务 器 。 

。 安装 邮件 传输 代理 (Mail Transport Agent, MTA) , 例如 Sendmail, 用 于 向 用 户 发 送 邮 件 。 

。 安装 适用 于 生产 环境 的 Web 服务 器 ， 例 如 Gunicorn 或 uWSGI。 

。 为 了 启用 安全 HITP， 购 买 、 安 装 并 配置 SSL 证 书 。 

。 (可 选 ， 但 强烈 推荐 ) 安装 前 端 反 向 代理 服务 器 ， 例 如 nginx 或 Apache。 反 向 代理 服务 
器 能 直接 服务 于 静态 文件 ， 而 把 其 他 请 求 转发 给 程序 使 用 的 Web 服务 器 。Web 服务 器 
监听 localhost 中 的 一 个 私有 端口 。 

。 强化 服务 器 。 这 一 过 程 包含 多 项 任务 ， 目 标 在 于 降低 服务 器 被 攻击 的 可 能 性 ， 例 如 安装 
防火 墙 以 及 删除 不 用 的 软件 和 服务 等 。 






































17.5.2 ”导入 环境 变量 

和 Heroku 中 的 程序 一 样 ， 运 行 在 独立 服务 器 上 的 程序 也 要 依赖 某 些 设置 ， 例 如 数据 库 URL.、 
电子 邮件 服务 器 密令 以 及 配置 名 。 这 些 设置 保存 在 环境 变量 中 ， 局 动 服务 器 之 前 必须 导入 。 
由 于 没有 Heroku 客户 端 和 Foreman 来 导入 变量 ， 这 个 任务 需要 在 启动 过 程 中 由 程序 本 身 
完成 。 示 例 17-9 中 这 段 简短 的 代码 能 加 载 并 解析 Foreman 使 用 的 .env 文件 。 在 创建 程序 
实例 代码 之 前 ， 可 以 将 这 段 代码 添加 到 启动 脚本 manage.py 中 。 





























示例 17-9 manage.py: 从 .env 文件 中 导入 环境 变量 


if os.path.exists('.env'): 








print('Importing environment from .env...') 
for line in open('.env'): 
var = line.strip().split('=') 
if len(var) == 2: 
os.environ[var[0]] = var[1] 


.eny 文件 中 至 少 要 包含 FLASK_CONFIG 变量 ， 用 以 选择 要 使 用 的 配置 。 


17.5.3 配置 日 志 
在 基于 Unix 的 服务 器 中 ， 日 志 可 发 送 给 守护 进程 syslog。 我 们 可 专门 为 Unix 创建 一 个 新 
配置 ， 继 承 自 ProductionConfig， 如 示例 17-10 所 示 。 





示例 17-10 ”config.py: Unix 配置 示例 
class UnixConfig(ProductionConfig): 
@classmethod 
def init app(cls, app): 
ProductionConfig.init_app(app) 


# 写 入 系统 日 志 

import logging 

from logging.handlers import SysLogHandler 
syslog_handler = SysLogHandler() 
syslog_handler .setLevel(logging.WARNING) 
app. Logger .addHandler(syslog_handler) 


这 样 配 置 之 后 ， 程 序 的 日 志 会 写 入 /var/log/messages。 如 果 需 要 ， 我 们 还 可 以 配置 系统 日 
志 服 务 ， 从 而 把 日 志 写 入 别 的 文件 或 者 发 送 到 其 他 设备 中 。 




















如 果 你 从 GitHub 上 克隆 了 这 个 程序 的 Git 仓库 ， 那 么 可 以 执行 git checkout 
17d 签 出 程序 的 这 个 版 本 。 
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第 18 章 


其 他 资源 





恭喜 ， 你 快 读 完 本 书 了 。 和 希望 本 书 洱 盖 的 话题 能 为 你 打下 坚实 的 基础 ， 让 你 开始 使 用 Flask 
开发 程序 。 书 中 的 示例 代码 是 开源 的 ， 基 于 一 个 宽松 的 许可 协议 发 布 ， 所 以 你 可 以 在 项 目 
中 尽情 使 用 其 中 代码 ， 即 便 是 用 于 商业 项 目 。 在 这 最 后 的 简短 一 章 中 ， 我 列 出 了 一 些 建议 
和 资源 ， 和 希望 能 为 你 继续 使 用 Flask 提供 一 些 帮助 。 


也 的 上 -= 
18.1 使 用 集成 开发 环境 
在 集成 开发 环境 (Integrated Development Environment，IDE) 中 开发 Flask 程序 非常 方便 ， 
因为 代码 补 全 和 交互 式 调 试 器 等 功能 可 以 显著 提升 编程 的 速度 。 以 下 是 几 个 适合 进行 Flask 
开发 的 IDE。 














。 PyCharm (http://www.jetbrains.com/pycharm/) :JetBrains 开发 的 商用 IDE, 有 社区 版 (免费 ) 
和 专业 版 (付费 ) ,两 个 版 本 都 兼容 Flask 程序 ,可 在 Linux、Mac OS X 和 Windows 中 使 用 。 

。 PyDev (http://pydev.org/) : 这 是 基于 Eclipse 的 开源 IDE， 可 在 Linux、Mac OS X 和 
Windows 中 使 用 。 

。 Python Tools for Visual Studio (http://pytools.codeplex.com/) : 这 是 免费 IDE， 作 为 微软 
Visual Studio 的 一 个 扩展 ， 只 能 在 微软 Windows 中 使 用 。 








配置 Flask 程序 在 调试 器 中 启动 时 ， 记 得 为 runserver 命令 加 入 --passthrough- 

errors --no-reload 选项 。 第 一 个 选项 禁用 Flask 对 错误 的 缓存 ， 这 样 处 理 请 

求 过 程 中 抛 出 的 异常 才 会 传 到 调试 器 中 。 第 二 个 选项 禁用 重 载 模块 ， 而 这 个 模 
会 搅乱 某 些 调试 器 。 
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8.2 查找 Flask 扩 展 


书 中 的 示例 程序 用 到 了 很 多 扩展 和 包 ， 不 过 还 有 很 多 有 用 的 扩展 没有 介绍 。 下 面 列 出 了 
他 一 些 值得 研究 的 包 。 








Flask-Babel (https://pythonhosted.org/Flask-Babel/) : 提供 国际 化 和 本 地 化 支持 。 
FLask-RESTful (http://flask-restful.readthedocs.org/en/latest/) : 开发 REST API 的 工具 。 
Celery (http://docs.celeryproject.org/en/latest/) : 处 理 后 台 作 业 的 任务 队列 。 

Frozen-Flask (https://pythonhosted.org/Frozen-Flask/) : 把 Flask 程序 转换 成 静态 网 站 。 
Flask-DebugToolbar (https://github.com/mgood/flask-debugtoolbar) : 在 浏览 器 中 使 用 的 
调试 工具 。 

Flask-Assets (https://github.com/miracle2k/flask-assets) : 用 于 合并 、 压 缩 、 编 译 CSS 和 
JavaScript 静态 资源 文件 。 

Flask-OAuth (http://pythonhosted.org/Flask-OAuth/) : 使 用 OAuth 服务 进行 认证 。 
Flask-OpenID (http://pythonhosted.org/Flask-OpenID/) : 使 用 OpenID 服务 进行 认证 。 
Flask-WhooshAlchemy (https://pythonhosted.org/Flask-WhooshAlchemy/) : 使 用 Whoosh 
(http://pythonhosted.org/Whoosh/) 实现 Flask-SQLAlchemy 模型 的 全 文 搜索 。 
Flask-KVsession (http://flask-kvsession.readthedocs.org/en/latest/) : 使 用 服务 器 端 存储 实 
现 的 另 一 种 用 户 会 话 。 










































































如 果 项 目 中 的 某 些 功能 无 法 使 用 本 书 介绍 的 扩展 和 包 实 现 ， 那 么 你 首先 可 以 到 Flask 官方 
扩展 网 站 (http://flask.pocoo.org/extensions/) 查找 其 他 扩展 。 其 他 可 以 搜寻 扩展 的 地 方 有 : 
Python Package Index (http:/pypi.python.org/) 、GitHub (http://github.com/) 和 BitBucket 
(http://bitbucket.org/) 。 

18.3 参与 Flask 开 发 

如 果 没 有 社区 开发 者 的 贡献 ，Flask 不 会 如 此 优秀 。 现 在 你 已 经 成 为 社区 的 一 份子 ， 也 从 
众多 志愿 者 的 劳动 中 受益 ， 所 以 你 应 该 攻 虑 通过 某 种 方式 来 回馈 社区 。 如 果 你 不 知 从 何 入 
手 ， 可 考虑 下 面 这 些 建议 : 





审阅 Flask 或 者 你 最 喜欢 的 相关 项 目 文 档 ， 提 交 修 正 或 改进 ， 

把 文档 翻译 成 其 他 语言 

在 问答 网 站 上 回答 问题 ， 例 如 Stack Overflow (http://stackoverflow.com/) ; 
在 用 户 组 的 聚会 或 者 会 议 上 和 同行 讨论 你 的 工作 ; 

对 于 你 使 用 的 包 中 的 错误 ， 贡献 修正 和 改进 建议 ; 

开发 新 Flask 扩展 ， 开 源 发 布 ; 

开源 自己 的 程序 。 








希望 你 能 使 用 上 述 或 者 其 他 有 意义 的 方式 为 社区 做 贡献 。 如 果 你 这 么 做 了 ， 那 我 由 囊 地 感谢 你 ! 
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关于 封面 图 


本 书 封面 上 的 动物 是 比 利 牛 斯 歼 犬 (家 犬 的 一 种 )。 这 种 大 型 西班牙 犬 的 祖先 是 一 种 名 为 
马 鲁 索 斯 大 的 家 畜 守 卫 犬 ， 这 种 犬 最 早 由 希腊 人 和 罗马 人 饲养 ， 现 已 灭绝 。 不 过 ， 马 鲁 索 
斯 大 在 现今 多 种 常见 犬 类 的 繁育 过 程 中 都 扮演 了 重要 角色 ， 例 如 罗 威 那 犬 、 大 丹 犬 、 纽 芬 
兰 犬 和 卡 斯 罗 犬 。 直 到 1977 年 ， 比 利 牛 斯 獒 犬 才 被 确认 为 纯 种 大 。 美 国 比 利 牛 斯 獒 大 俱 
乐 部 致力 于 把 这 种 犬 作为 宠物 在 美国 推广 。 


西班牙 内 战 结束 后 ， 原 产地 的 比 利 牛 斯 熬 大 数量 急剧 下 降 。 这 一 大 种 能 幸存 下 来 完全 有 赖 
于 分 散在 全 国 各 地 的 专职 饲养 员 。 比 利 牛 斯 歼 犬 的 现代 基因 库 源 于 这 一 战 后 种 群 ， 所 以 它 
们 很 容易 得 遗传 病 ， 例 如 髋 关 市 发 育 不 良 。 现 在 ， 负 责任 的 主人 都 会 在 饲养 前 对 狗 做 疾病 
检查 和 XX 光照 射 以 排除 艇 关 市 异常 。 











成 年 雄性 比 利 牛 斯 熬 犬 完全 长 成 后 可 重 达 200 英 磅 ， 所 以 饲养 这 种 狗 要 保证 充足 的 训练 和 
时 狗 时 间 。 比 利 牛 斯 获 犬 虽然 体型 很 大 ， 而 且 曾 作为 抵挡 能 和 狼 的 猎 大 ， 但 其 性 情 温 顺 ， 
是 一 种 优秀 的 家 犬 。 人 类 可 以 放心 地 让 这 种 狗 照看 儿童 和 守护 庭院 ， 而 且 可 以 将 其 和 其 他 
狗 一 起 驯养 。 比 利 牛 斯 獒 大 有 一 定 的 社交 能 力 和 较 强 的 领导 力 ， 在 家 庭 环境 的 丢 陶 之 下 ， 
它们 已 经 成 为 一 种 优秀 的 守护 大 和 伙伴 。 

















本 书 的 封面 图 片 出 自 Wood 的 Animate Creation 一 书 。 
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Flask Web 开 发 : 基于 Python 的 Web 应 用 开发 实战 


作为 Python Web 开 发 的 微 框架 ，Flask 独 树 一 帜 。 它 不 会 强迫 开发 者 遵循 
预 置 的 开发 规范 ， 为 开发 者 提供 了 自由 度 和 创意 空间 。 


本 书 作 者 拥有 25 年 软件 开发 经 验 ， 而 本 书 则 采用 讲解 与 实例 相 结 合 的 方 
式 ， 不仅 介绍 了 Flask 安 装 、 使 用 等 基础 知识 ， 而 且 还 带领 读者 一 步 一步 
地 开发 了 社交 博客 Flasky。 即 使 从 未 接触 Flask， 你 也 能 轻松 学 会 构建 完 
整 的 web 应 用 。 通 读本 书 ， 你 能 熟悉 Flask 的 核心 功能 ， 并 掌握 数据 库 迁 
移 、Web 服 务 通信 等 高 级 Web 技 术 。 


本 书 不 仅 适 合 初级 Web 开 发 人 员 学 习 阅 读 ， 更 是 Python 程序 员 用 来 学 习 
高 级 Web 开 发 技术 的 优秀 参考 书 。 
是 学 习 Flask 应 用 的 基本 结构 ， 编 写 示例 应 用 ， 


目 使 用 必 备 的 组 件 ， 包 括 模板 、 数 据 库 、Web 表 单 和 电子 邮件 支 
持 ; 


蛋 使 用 包 和 模块 构建 可 伸缩 的 大 型 应 用 ， 
蛋 实现 用 户 认证 、 角 色 和 个 人 资料 ; 
目 在 博客 网 站 中 重用 模板 、 分 页 显示 列表 以 及 使 用 富 文本 ; 


蛋 使 用 基于 Flask 的 REST 式 API， 在 智能 手机 、 平 板 电脑 和 其 他 第 三 
方 客户 端 上 实现 可 用 功能 ， 


目 学 习 运 行 单元 测试 以 及 提升 性 能 ， 
目 将 Web 应 用 部 署 到 生产 服务 器 。 


Miguel Grinberg 拥有 25 年 开发 经 验 的 高 级 软件 工程 师 ， 目 前 为 广播 公司 


开发 视频 软件 。 他 常 在 个 人 博客 (blog.miguelgrinberg.com) 上 撰写 各 类 
博文 ， 内 容 主 要 涉及 Web 开 发 、 机 器 人 技术 、 摄 影 偶尔 也 会 有 一 些 影 
评 。 他 和 妻子 、 四 个 孩子 、 两 只 狗 和 一 只 猫 共同 生活 在 俄勒冈 州 波 特 兰 
市 。Twitter: @miguelgrinberg。 


“好 久 没 有 看 到 这 么 棒 的 技术 书 


了 ! 它 从 安装 与 环境 设置 讲 起 ， 
目标 则 是 搭建 服务 器 端 Web 应 
用 。 本 书 直 接 了 当地 给 出 了 读 
者 必 知 必 会 的 知识 ， 为 初学 者 
提供 了 进一步 探索 的 起 点 ， 也 
让 中 高 级 读者 能 够 掌握 最 佳 实 
践 。” 


“我 不 是 新 手 ， 做 过 Flask 应 用 开 


发 ， 我 以 为 自己 完全 了 解 相关 
基础 知识 。 但 实际 阅读 中 ， 我 
却 折 了 很 多 页 ， 时 不 时 会 翻阅 
相关 的 知识 点 。 其 中 的 技巧 和 
提示 总 能 让 我 茅 塞 顿 开 …… 真 
是 有 幸 读 了 这 本 书 ! ” 


“本 书 的 组 织 结构 非常 合理 。 读 


完 本 书 ， 我 也 亲身 参与 构建 了 
Web 应 用 ， 真 正 拾级 而 上 掌握 
了 强大 的 Flask 开 发 。” 
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